diff options
Diffstat (limited to 'devdocs/vagrant')
147 files changed, 3663 insertions, 0 deletions
diff --git a/devdocs/vagrant/boxes%2Fbase.html b/devdocs/vagrant/boxes%2Fbase.html new file mode 100644 index 00000000..1f3b2e14 --- /dev/null +++ b/devdocs/vagrant/boxes%2Fbase.html @@ -0,0 +1,32 @@ +<h1 id="creating-a-base-box"> Creating a Base Box </h1> <p>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").</p> <p>For example, the Ubuntu boxes provided by the Vagrant project (such as "precise64") are base boxes. They were created from a minimal Ubuntu install from an ISO, rather than repackaging an existing environment.</p> <p>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.</p> <blockquote class="alert alert-warning"> <p><strong>Advanced topic!</strong> 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.</p> </blockquote> +<h2 id="what-39-s-in-a-base-box-"> What's in a Base Box? </h2> <p>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:</p> <ul> <li>Package manager </li> <li>SSH </li> <li>SSH user so Vagrant can connect </li> <li>Perhaps Chef, Puppet, etc. but not strictly required. </li> </ul> <p>In addition to this, each <a href="../providers/index">provider</a> 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.</p> <h2 id="creating-a-base-box-1"> Creating a Base Box </h2> <p>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.</p> <p>This page will document some general guidelines for creating base boxes, however, and will link to provider-specific guides for creating base boxes.</p> <p>Provider-specific guides for creating base boxes are linked below:</p> <ul> <li> +<a href="../docker/boxes">Docker Base Boxes</a> </li> <li> +<a href="../hyperv/boxes">Hyper-V Base Boxes</a> </li> <li> +<a href="../vmware/boxes">VMware Base Boxes</a> </li> <li> +<a href="../virtualbox/boxes">VirtualBox Base Boxes</a> </li> </ul> <h3 id="packer-and-vagrant-cloud"> Packer and Vagrant Cloud </h3> <p>We strongly recommend using <a href="https://www.packer.io">Packer</a> to create reproducible builds for your base boxes, as well as automating the builds. Read more about <a href="https://www.packer.io/guides/packer-on-cicd/build-image-in-cicd.html">automating Vagrant box creation with Packer</a> in the Packer documentation.</p> <h3 id="disk-space"> Disk Space </h3> <p>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.</p> <p>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.</p> <h3 id="memory"> Memory </h3> <p>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 <code>vagrant up</code> 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.</p> <h3 id="peripherals-audio-usb-etc-"> Peripherals (Audio, USB, etc.) </h3> <p>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.</p> <h2 id="default-user-settings"> Default User Settings </h2> <p>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.</p> <p>If you are creating a base box for private use, you should try <em>not</em> to follow these, as they open up your base box to security risks (known users, passwords, private keys, etc.).</p> <h3 id="quot-vagrant-quot-user"> "vagrant" User </h3> <p>By default, Vagrant expects a "vagrant" user to SSH into the machine as. This user should be setup with the <a href="https://github.com/hashicorp/vagrant/tree/master/keys">insecure keypair</a> 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.</p> <p>To configure SSH access with the insecure keypair, place the public key into the <code>~/.ssh/authorized_keys</code> file for the "vagrant" user. Note that OpenSSH is very picky about file permissions. Therefore, make sure that <code>~/.ssh</code> has <code>0700</code> permissions and the authorized keys file has <code>0600</code> permissions.</p> <p>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.</p> <h3 id="root-password-quot-vagrant-quot-"> Root Password: "vagrant" </h3> <p>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.</p> <p>Publicly available base boxes usually use a root password of "vagrant" to keep things easy.</p> <h3 id="password-less-sudo"> Password-less Sudo </h3> <p>This is <strong>important!</strong>. 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.</p> <p>To begin, some minimal installations of operating systems do not even include <code>sudo</code> by default. Verify that you install <code>sudo</code> in some way.</p> <p>After installing sudo, configure it (usually using <code>visudo</code>) to allow passwordless sudo for the "vagrant" user. This can be done with the following line at the end of the configuration file:</p> <div class="highlight"><pre class="highlight plaintext">vagrant ALL=(ALL) NOPASSWD: ALL +</pre></div> +<p>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 <code>requiretty</code> in it. Remove that if it exists. This allows sudo to work properly without a tty. Note that you <em>can</em> configure Vagrant to request a pty, which lets you keep this configuration. But Vagrant by default does not do this.</p> <h3 id="ssh-tweaks"> SSH Tweaks </h3> <p>In order to keep SSH speedy even when your machine or the Vagrant machine is not connected to the internet, set the <code>UseDNS</code> configuration to <code>no</code> in the SSH server configuration.</p> <p>This avoids a reverse DNS lookup on the connecting SSH client which can take many seconds.</p> <h2 id="windows-boxes"> Windows Boxes </h2> <p>Supported Windows guest operating systems: - Windows 7 - Windows 8 - Windows Server 2008 - Windows Server 2008 R2 - Windows Server 2012 - Windows Server 2012 R2</p> <p>Windows Server 2003 and Windows XP are <em>not</em> supported, but if you are a die hard XP fan <a href="https://stackoverflow.com/a/18593425/18475">this</a> may help you.</p> <h3 id="base-windows-configuration"> Base Windows Configuration </h3> <ul> <li>Turn off UAC </li> <li>Disable complex passwords </li> <li>Disable "Shutdown Tracker" </li> <li>Disable "Server Manager" starting at login (for non-Core) </li> </ul> <p>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.</p> <div class="highlight"><pre class="highlight plaintext">reg add HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Policies\System /v EnableLUA /d 0 /t REG_DWORD /f /reg:64 +</pre></div> +<h3 id="base-winrm-configuration"> Base WinRM Configuration </h3> <p>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:</p> <div class="highlight"><pre class="highlight plaintext">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 +</pre></div> +<h3 id="additional-winrm-1-1-configuration"> Additional WinRM 1.1 Configuration </h3> <p>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.</p> <ol> <li>Ensure the Windows PowerShell feature is installed </li> <li>Change the WinRM port to 5985 or upgrade to WinRM 2.0 </li> </ol> <p>The following commands will change the WinRM 1.1 port to what's expected by Vagrant:</p> <div class="highlight"><pre class="highlight plaintext">netsh firewall add portopening TCP 5985 "Port 5985" +winrm set winrm/config/listener?Address=*+Transport=HTTP @{Port="5985"} +</pre></div> +<h2 id="other-software"> Other Software </h2> <p>At this point, you have all the common software you absolutely <em>need</em> for your base box to work with Vagrant. However, there is some additional software you can install if you wish.</p> <p>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.</p> <p>Installing this is outside the scope of this page, but should be fairly straightforward.</p> <p>In addition to this, feel free to install and configure any other software you want available by default for this base box.</p> <h2 id="packaging-the-box"> Packaging the Box </h2> <p>Packaging the box into a <code>box</code> 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.</p> <h2 id="distributing-the-box"> Distributing the Box </h2> <p>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 <a href="https://www.vagrantup.com/docs/vagrant-cloud">HashiCorp's Vagrant Cloud</a>.</p> <p>You can upload both public and private boxes to this service.</p> <h2 id="testing-the-box"> Testing the Box </h2> <p>To test the box, pretend you are a new user of Vagrant and give it a shot:</p> <div class="highlight"><pre class="highlight plaintext">$ vagrant box add --name my-box /path/to/the/new.box +... +$ vagrant init my-box +... +$ vagrant up +... +</pre></div> +<p>If you made a box for some other provider, be sure to specify the <code>--provider</code> option to <code>vagrant up</code>. If the up succeeded, then your box worked!</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/boxes/base.html" class="_attribution-link">https://www.vagrantup.com/docs/boxes/base.html</a> + </p> +</div> diff --git a/devdocs/vagrant/boxes%2Fformat.html b/devdocs/vagrant/boxes%2Fformat.html new file mode 100644 index 00000000..86e9aadd --- /dev/null +++ b/devdocs/vagrant/boxes%2Fformat.html @@ -0,0 +1,32 @@ +<h1 id="box-file-format"> Box File Format </h1> <p>In the past, boxes were just <a href="https://en.wikipedia.org/wiki/Tar_(computing)">tar files</a> of VirtualBox exports. With Vagrant supporting multiple <a href="../providers/index">providers</a> and <a href="versioning">versioning</a> now, box files are slightly more complicated.</p> <p>Box files made for Vagrant 1.0.x (the VirtualBox export <code>tar</code> files) continue to work with Vagrant today. When Vagrant encounters one of these old boxes, it automatically updates it internally to the new format.</p> <p>Today, there are three different components:</p> <ul> <li> +<p>Box File - This is a compressed (<code>tar</code>, <code>tar.gz</code>, <code>zip</code>) 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.</p> </li> <li> +<p>Box Catalog Metadata - This is a JSON document (typically exchanged during interactions with <a href="https://www.vagrantup.com/docs/vagrant-cloud">HashiCorp's Vagrant Cloud</a>) 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.</p> </li> <li> +<p>Box Information - This is a JSON document that can provide additional information about the box that displays when a user runs <code>vagrant box list -i</code>. More information is provided <a href="info">here</a>.</p> </li> </ul> <p>The first two components are covered in more detail below.</p> <h2 id="box-file"> Box File </h2> <p>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.</p> <p>Box files are compressed using <code>tar</code>, <code>tar.gz</code>, or <code>zip</code>. The contents of the archive can be anything, and is specific to each <a href="../providers/index">provider</a>. Vagrant core itself only unpacks the boxes for use later.</p> <p>Within the archive, Vagrant does expect a single file: <code>metadata.json</code>. This is a JSON file that is completely unrelated to the above box catalog metadata component; there is only one <code>metadata.json</code> 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.</p> <p><code>metadata.json</code> 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 <code>metadata.json</code> would look like this:</p> <div class="highlight"><pre class="highlight json" data-language="json">{ + "provider": "virtualbox" +} +</pre></div> +<p>If there is no <code>metadata.json</code> 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.</p> <p>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.</p> <h2 id="box-metadata"> Box Metadata </h2> <p>The metadata is an optional component for a box (but highly recommended) that enables <a href="versioning">versioning</a>, updating, multiple providers from a single file, and more.</p> <blockquote class="alert alert-block alert-info"> <p><strong>You do not need to manually make the metadata.</strong> If you have an account with <a href="https://www.vagrantup.com/docs/vagrant-cloud">HashiCorp's Vagrant Cloud</a>, you can create boxes there, and HashiCorp's Vagrant Cloud automatically creates the metadata for you. The format is still documented here.</p> </blockquote> +<p>It is a JSON document, structured in the following way:</p> <div class="highlight"><pre class="highlight json" data-language="json">{ + "name": "hashicorp/precise64", + "description": "This box contains Ubuntu 12.04 LTS 64-bit.", + "versions": [ + { + "version": "0.1.0", + "providers": [ + { + "name": "virtualbox", + "url": "http://somewhere.com/precise64_010_virtualbox.box", + "checksum_type": "sha1", + "checksum": "foo" + } + ] + } + ] +} +</pre></div> +<p>As you can see, the JSON document can describe multiple versions of a box, multiple providers, and can add/remove providers in different versions.</p> <p>This JSON file can be passed directly to <code>vagrant box add</code> 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 <code>url</code> key in the JSON can also be a file path. If multiple providers are available, Vagrant will ask what provider you want to use.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/boxes/format.html" class="_attribution-link">https://www.vagrantup.com/docs/boxes/format.html</a> + </p> +</div> diff --git a/devdocs/vagrant/boxes%2Finfo.html b/devdocs/vagrant/boxes%2Finfo.html new file mode 100644 index 00000000..2b41e052 --- /dev/null +++ b/devdocs/vagrant/boxes%2Finfo.html @@ -0,0 +1,16 @@ +<h1 id="additional-box-information"> Additional Box Information </h1> <p>When creating a Vagrant box, you can supply additional information that might be relevant to the user when running <code>vagrant box list -i</code>. For example, you could package your box to include information about the author of the box and a website for users to learn more:</p> <div class="highlight"><pre class="highlight plaintext">brian@localghost % vagrant box list -i +hashicorp/precise64 (virtualbox, 1.0.0) + - author: brian + - homepage: https://www.vagrantup.com +</pre></div> +<h2 id="box-info"> Box Info </h2> <p>To accomplish this, you simply need to include a file named <code>info.json</code> when creating a <a href="base">base box</a> which is a JSON document containing any and all relevant information that will be displayed to the user when the <code>-i</code> option is used with <code>vagrant box list</code>.</p> <div class="highlight"><pre class="highlight json" data-language="json">{ + "author": "brian", + "homepage": "https://example.com" +} +</pre></div> +<p>There are no special keys or values in <code>info.json</code>, and Vagrant will print each key and value on its own line.</p> <p>The <a href="format">Box File Format</a> provides more information about what else goes into a Vagrant box.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/boxes/info.html" class="_attribution-link">https://www.vagrantup.com/docs/boxes/info.html</a> + </p> +</div> diff --git a/devdocs/vagrant/boxes%2Fversioning.html b/devdocs/vagrant/boxes%2Fversioning.html new file mode 100644 index 00000000..0309e9c0 --- /dev/null +++ b/devdocs/vagrant/boxes%2Fversioning.html @@ -0,0 +1,6 @@ +<h1 id="box-versioning"> Box Versioning </h1> <p>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.</p> <p>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.</p> <p>This page will cover how to use versioned boxes. It does <em>not</em> cover how to update your own custom boxes with versions. That is covered in <a href="base">creating a base box</a>.</p> <h2 id="viewing-versions-and-updating"> Viewing Versions and Updating </h2> <p><code>vagrant box list</code> only shows <em>installed</em> versions of boxes. If you want to see all available versions of a box, you will have to find the box on <a href="https://www.vagrantup.com/docs/vagrant-cloud">HashiCorp's Vagrant Cloud</a>. An easy way to find a box is to use the url <code>https://vagrantcloud.com/$USER/$BOX</code>. For example, for the <code>hashicorp/precise64</code> box, you can find information about it at <code>https://vagrantcloud.com/hashicorp/precise64</code>.</p> <p>You can check if the box you are using is outdated with <code>vagrant box outdated</code>. This can check if the box in your current Vagrant environment is outdated as well as any other box installed on the system.</p> <p>Finally, you can update boxes with <code>vagrant box update</code>. This will download and install the new box. This <em>will not</em> 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.</p> <h2 id="version-constraints"> Version Constraints </h2> <p>You can constrain a Vagrant environment to a specific version or versions of a box using the <a href="../vagrantfile/index">Vagrantfile</a> by specifying the <code>config.vm.box_version</code> option.</p> <p>If this option is not specified, the latest version is always used. This is equivalent to specifying a constraint of ">= 0".</p> <p>The box version configuration can be a specific version or a constraint of versions. Constraints can be any combination of the following: <code>= X</code>, <code>> X</code>, <code>< X</code>, <code>>= X</code>, <code><= X</code>, <code>~> X</code>. You can combine multiple constraints by separating them with commas. All the constraints should be self explanatory except perhaps for <code>~></code>, known as the "pessimistic constraint". Examples explain it best: <code>~> 1.0</code> is equivalent to <code>>= 1.0, < 2.0</code>. And <code>~> 1.1.5</code> is equivalent to <code>>= 1.1.5, < 1.2.0</code>.</p> <p>You can choose to handle versions however you see fit. However, many boxes in the public catalog follow <a href="http://semver.org/">semantic versioning</a>. 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 <code>~> 1.0</code> because you know it is safe no matter what version is in that range.</p> <p>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 <code>X.Y.Z</code> where <code>X</code>, <code>Y</code>, and <code>Z</code> are all positive integers.</p> <h2 id="automatic-update-checking"> Automatic Update Checking </h2> <p>Using the <a href="../vagrantfile/index">Vagrantfile</a>, you can also configure Vagrant to automatically check for updates during any <code>vagrant up</code>. This is enabled by default, but can easily be disabled with <code>config.vm.box_check_update = false</code> in your Vagrantfile.</p> <p>When this is enabled, Vagrant will check for updates on every <code>vagrant up</code>, not just when the machine is being created from scratch, but also when it is resuming, starting after being halted, etc.</p> <p>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 <code>vagrant box update</code>.</p> <p>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.</p> <h2 id="pruning-old-versions"> Pruning Old Versions </h2> <p>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 <code>vagrant box remove</code>. You can see all the boxes that are installed using <code>vagrant box list</code>.</p> <p>Another option is to use <code>vagrant box prune</code> command to remove all installed boxes that are outdated and not currently in use.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/boxes/versioning.html" class="_attribution-link">https://www.vagrantup.com/docs/boxes/versioning.html</a> + </p> +</div> diff --git a/devdocs/vagrant/boxes.html b/devdocs/vagrant/boxes.html new file mode 100644 index 00000000..b53366a2 --- /dev/null +++ b/devdocs/vagrant/boxes.html @@ -0,0 +1,14 @@ +<h1 id="boxes"> Boxes </h1> <p>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.</p> <p>The <code>vagrant box</code> utility provides all the functionality for managing boxes. You can read the documentation on the <a href="cli/box">vagrant box</a> command for more information.</p> <p>The easiest way to use a box is to add a box from the <a href="https://vagrantcloud.com/boxes/search">publicly available catalog of Vagrant boxes</a>. You can also add and share your own customized boxes on this website.</p> <p>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.</p> <p>You can learn all about boxes by reading this page as well as the sub-pages in the navigation to the left.</p> <h2 id="discovering-boxes"> Discovering Boxes </h2> <p>The easiest way to find boxes is to look on the <a href="https://vagrantcloud.com/boxes/search">public Vagrant box catalog</a> 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.</p> <p>The boxes on the public catalog work with many different <a href="providers/index">providers</a>. Whether you are using Vagrant with VirtualBox, VMware, AWS, etc. you should be able to find a box you need.</p> <p>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:</p> <div class="highlight"><pre class="highlight plaintext">$ vagrant box add USER/BOX +</pre></div> +<p>For example: <code>vagrant box add hashicorp/precise64</code>. You can also quickly initialize a Vagrant environment with <code>vagrant init hashicorp/precise64</code>.</p> <blockquote class="alert alert-warning" role="alert"> <p><strong>Namespaces do not guarantee canonical boxes!</strong> 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.</p> </blockquote> <h2 id="official-boxes"> Official Boxes </h2> <p>HashiCorp (the makers of Vagrant) publish a basic Ubuntu 12.04 (32 and 64-bit) box that is available for minimal use cases. It is highly optimized, small in size, and includes support for Virtualbox and VMware. You can use it like this:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ vagrant init hashicorp/precise64 +</pre></div> +<p>or you can update your <code>Vagrantfile</code> as follows:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.box = "hashicorp/precise64" +end +</pre></div> +<p>For other users, we recommend the <a href="https://vagrantcloud.com/bento">Bento boxes</a>. The Bento boxes are <a href="https://github.com/chef/bento">open source</a> and built for a number of providers including VMware, Virtualbox, and Parallels. There are a variety of operating systems and versions available.</p> <p>These are the only two officially-recommended box sets.</p> <blockquote class="alert alert-warning" role="alert"> <p><strong>It is often a point of confusion</strong>, 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.</p> </blockquote><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/boxes.html" class="_attribution-link">https://www.vagrantup.com/docs/boxes.html</a> + </p> +</div> diff --git a/devdocs/vagrant/cli%2Faliases.html b/devdocs/vagrant/cli%2Faliases.html new file mode 100644 index 00000000..ce38a939 --- /dev/null +++ b/devdocs/vagrant/cli%2Faliases.html @@ -0,0 +1,21 @@ +<h1 id="aliases"> Aliases </h1> <p>Inspired in part by Git's own <a href="https://git-scm.com/book/en/v2/Git-Basics-Git-Aliases">alias functionality</a>, aliases make your Vagrant experience simpler, easier, and more familiar by allowing you to create your own custom Vagrant commands.</p> <p>Aliases can be defined within <code>VAGRANT_HOME/aliases</code> file, or in a custom file defined using the <code>VAGRANT_ALIAS_FILE</code> environment variable, in the following format:</p> <div class="highlight"><pre class="highlight plaintext"># basic command-level aliases +start = up +stop = halt + +# advanced command-line aliases +eradicate = !vagrant destroy && rm -rf .vagrant +</pre></div> +<p>In a nutshell, aliases are defined using a standard <code>key = value</code> format, where the <code>key</code> is the new Vagrant command, and the <code>value</code> is the aliased command. Using this format, there are two types of aliases that can be defined: internal and external aliases.</p> <h2 id="internal-aliases"> Internal Aliases </h2> <p>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 <em>should</em> exist. For example, if <code>vagrant stop</code> feels more intuitive than <code>vagrant halt</code>, the following alias definitions would make that change possible:</p> <div class="highlight"><pre class="highlight plaintext">stop = halt +</pre></div> +<p>This makes the following commands equivalent:</p> <div class="highlight"><pre class="highlight plaintext">vagrant stop +vagrant halt +</pre></div> +<h2 id="external-aliases"> External Aliases </h2> <p>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 <code>!</code> 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 <code>vagrant metrics</code> command that returns the required information in an easy-to-read format, like so:</p> <div class="highlight"><pre class="highlight plaintext">metrics = !ps aux | grep "[V]BoxHeadless" | grep $(cat .vagrant/machines/default/virtualbox/id) | awk '{ printf("CPU: %.02f%%, Memory: %.02f%%", $3, $4) }' +</pre></div> +<p>The above alias, from within the context of an active Vagrant project, would print the CPU and memory utilization directly to the console:</p> <div class="highlight"><pre class="highlight plaintext">CPU: 4.20%, Memory: 11.00% +</pre></div><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/cli/aliases.html" class="_attribution-link">https://www.vagrantup.com/docs/cli/aliases.html</a> + </p> +</div> diff --git a/devdocs/vagrant/cli%2Fbox.html b/devdocs/vagrant/cli%2Fbox.html new file mode 100644 index 00000000..c271661d --- /dev/null +++ b/devdocs/vagrant/cli%2Fbox.html @@ -0,0 +1,39 @@ +<h1 id="box"> Box </h1> <p><strong>Command: <code>vagrant box</code></strong></p> <p>This is the command used to manage (add, remove, etc.) <a href="../boxes">boxes</a>.</p> <p>The main functionality of this command is exposed via even more subcommands:</p> <ul> <li> +<a href="#box-add"><code>add</code></a> </li> <li> +<a href="#box-list"><code>list</code></a> </li> <li> +<a href="#box-outdated"><code>outdated</code></a> </li> <li> +<a href="#box-prune"><code>prune</code></a> </li> <li> +<a href="#box-remove"><code>remove</code></a> </li> <li> +<a href="#box-repackage"><code>repackage</code></a> </li> <li> +<a href="#box-update"><code>update</code></a> </li> </ul> <h1 id="box-add"> Box Add </h1> <p><strong>Command: <code>vagrant box add ADDRESS</code></strong></p> <p>This adds a box with the given address to Vagrant. The address can be one of three things:</p> <ul> <li> +<p>A shorthand name from the <a href="https://vagrantcloud.com/boxes/search">public catalog of available Vagrant images</a>, such as "hashicorp/precise64".</p> </li> <li> +<p>File path or HTTP URL to a box in a <a href="https://vagrantcloud.com/boxes/search">catalog</a>. For HTTP, basic authentication is supported and <code>http_proxy</code> environmental variables are respected. HTTPS is also supported.</p> </li> <li> +<p>URL directly a box file. In this case, you must specify a <code>--name</code> flag (see below) and versioning/updates will not work.</p> </li> </ul> <p>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.</p> <h2 id="options"> Options </h2> <ul> <li> +<p><a href="#box-version-value"><code>--box-version VALUE</code></a> - 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".</p> </li> <li> +<p><a href="#cacert-certfile"><code>--cacert CERTFILE</code></a> - 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.</p> </li> <li> +<p><a href="#capath-certdir"><code>--capath CERTDIR</code></a> - 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.</p> </li> <li> +<p><a href="#cert-certfile"><code>--cert CERTFILE</code></a> - A client certificate to use when downloading the box, if necessary.</p> </li> <li> +<p><a href="#clean"><code>--clean</code></a> - 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.</p> </li> <li> +<p><a href="#force"><code>--force</code></a> - When present, the box will be downloaded and overwrite any existing box with this name.</p> </li> <li> +<p><a href="#insecure"><code>--insecure</code></a> - When present, SSL certificates will not be verified if the URL is an HTTPS URL.</p> </li> <li> +<p><a href="#provider-provider"><code>--provider PROVIDER</code></a> - 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.</p> </li> </ul> <h2 id="options-for-direct-box-files"> Options for direct box files </h2> <p>The options below only apply if you are adding a box file directly (when you are not using a catalog).</p> <ul> <li> +<p><a href="#checksum-value"><code>--checksum VALUE</code></a> - 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, <code>--checksum-type</code> must also be specified. If you are downloading from a catalog, the checksum is included within the catalog entry.</p> </li> <li> +<p><a href="#checksum-type-type"><code>--checksum-type TYPE</code></a> - The type of checksum that <code>--checksum</code> is if it is specified. Supported values are currently "md5", "sha1", and "sha256".</p> </li> <li> +<p><a href="#name-value"><code>--name VALUE</code></a> - Logical name for the box. This is the value that you would put into <code>config.vm.box</code> 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.</p> </li> </ul> <blockquote class="alert alert-warning"> <p><strong>Checksums for versioned boxes or boxes from HashiCorp's Vagrant Cloud:</strong> 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.</p> </blockquote> +<h1 id="box-list"> Box List </h1> <p><strong>Command: <code>vagrant box list</code></strong></p> <p>This command lists all the boxes that are installed into Vagrant.</p> <h1 id="box-outdated"> Box Outdated </h1> <p><strong>Command: <code>vagrant box outdated</code></strong></p> <p>This command tells you whether or not the box you are using in your current Vagrant environment is outdated. If the <code>--global</code> flag is present, every installed box will be checked for updates.</p> <p>Checking for updates involves refreshing the metadata associated with a box. This generally requires an internet connection.</p> <h2 id="options-1"> Options </h2> <ul> <li> +<a href="#global"><code>--global</code></a> - Check for updates for all installed boxes, not just the boxes for the current Vagrant environment. </li> </ul> <h1 id="box-prune"> Box Prune </h1> <p><strong>Command: <code>vagrant box prune</code></strong></p> <p>This command removes old versions of installed boxes. If the box is currently in use vagrant will ask for confirmation.</p> <h2 id="options-2"> Options </h2> <ul> <li> +<p><a href="#provider-provider-1"><code>--provider PROVIDER</code></a> - The specific provider type for the boxes to destroy.</p> </li> <li> +<p><a href="#dry-run"><code>--dry-run</code></a> - Only print the boxes that would be removed.</p> </li> <li> +<p><a href="#name-name"><code>--name NAME</code></a> - The specific box name to check for outdated versions.</p> </li> <li> +<p><a href="#force-1"><code>--force</code></a> - Destroy without confirmation even when box is in use.</p> </li> </ul> <h1 id="box-remove"> Box Remove </h1> <p><strong>Command: <code>vagrant box remove NAME</code></strong></p> <p>This command removes a box from Vagrant that matches the given name.</p> <p>If a box has multiple providers, the exact provider must be specified with the <code>--provider</code> flag. If a box has multiple versions, you can select what versions to delete with the <code>--box-version</code> flag or remove all versions with the <code>--all</code> flag.</p> <h2 id="options-3"> Options </h2> <ul> <li> +<p><a href="#box-version-value-1"><code>--box-version VALUE</code></a> - Version of version constraints of the boxes to remove. See documentation on this flag for <code>box add</code> for more details.</p> </li> <li> +<p><a href="#all"><code>--all</code></a> - Remove all available versions of a box.</p> </li> <li> +<p><a href="#force-2"><code>--force</code></a> - Forces removing the box even if an active Vagrant environment is using it.</p> </li> <li> +<p><a href="#provider-value"><code>--provider VALUE</code></a> - 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.</p> </li> </ul> <h1 id="box-repackage"> Box Repackage </h1> <p><strong>Command: <code>vagrant box repackage NAME PROVIDER VERSION</code></strong></p> <p>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 <code>vagrant box list</code>.</p> <p>When you add a box, Vagrant unpacks it and stores it internally. The original <code>*.box</code> file is not preserved. This command is useful for reclaiming a <code>*.box</code> file from an installed Vagrant box.</p> <h1 id="box-update"> Box Update </h1> <p><strong>Command: <code>vagrant box update</code></strong></p> <p>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 <code>--box</code> flag.</p> <p><small><i>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.</i></small></p> <p>If you just want to check if there are updates available, use the <code>vagrant box outdated</code> command.</p> <h2 id="options-4"> Options </h2> <ul> <li> +<p><a href="#box-value"><code>--box VALUE</code></a> - Name of a specific box to update. If this flag is not specified, Vagrant will update the boxes for the active Vagrant environment.</p> </li> <li> +<p><a href="#provider-value-1"><code>--provider VALUE</code></a> - When <code>--box</code> is present, this controls what provider-specific box to update. This is not required unless the box has multiple providers. Without the <code>--box</code> flag, this has no effect.</p> </li> </ul><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/cli/box.html" class="_attribution-link">https://www.vagrantup.com/docs/cli/box.html</a> + </p> +</div> diff --git a/devdocs/vagrant/cli%2Fcloud.html b/devdocs/vagrant/cli%2Fcloud.html new file mode 100644 index 00000000..12fa44e3 --- /dev/null +++ b/devdocs/vagrant/cli%2Fcloud.html @@ -0,0 +1,101 @@ +<h1 id="cloud"> Cloud </h1> <p><strong>Command: <code>vagrant cloud</code></strong></p> <p>This is the command used to manage anything related to <a href="https://vagrantcloud.com">Vagrant Cloud</a>.</p> <p>The main functionality of this command is exposed via subcommands:</p> <ul> <li> +<a href="#cloud-auth"><code>auth</code></a> </li> <li> +<a href="#cloud-box"><code>box</code></a> </li> <li> +<a href="#cloud-provider"><code>provider</code></a> </li> <li> +<a href="#cloud-publish"><code>publish</code></a> </li> <li> +<a href="#cloud-search"><code>search</code></a> </li> <li> +<a href="#cloud-version"><code>version</code></a> </li> </ul> <h1 id="cloud-auth"> Cloud Auth </h1> <p><strong>Command: <code>vagrant cloud auth</code></strong></p> <p>The <code>cloud auth</code> command is for handling all things related to authorization with Vagrant Cloud.</p> <ul> <li> +<a href="#cloud-auth-login"><code>login</code></a> </li> <li> +<a href="#cloud-auth-logout"><code>logout</code></a> </li> <li> +<a href="#cloud-auth-whoami"><code>whoami</code></a> </li> </ul> <h2 id="cloud-auth-login"> Cloud Auth Login </h2> <p><strong>Command: <code>vagrant cloud auth login</code></strong></p> <p>The login command is used to authenticate with <a href="https://www.vagrantup.com/docs/vagrant-cloud">HashiCorp's Vagrant Cloud</a> server. Logging in is only necessary if you are accessing protected boxes.</p> <p><strong>Logging in is not a requirement to use Vagrant.</strong> The vast majority of Vagrant does <em>not</em> require a login. Only certain features such as protected boxes.</p> <p>The reference of available command-line flags to this command is available below.</p> <h3 id="options"> Options </h3> <ul> <li> +<p><a href="#check"><code>--check</code></a> - 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.</p> </li> <li> +<p><a href="#logout"><code>--logout</code></a> - 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.</p> </li> <li> +<p><a href="#token"><code>--token</code></a> - 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.</p> </li> </ul> <h3 id="examples"> Examples </h3> <p>Securely authenticate to Vagrant Cloud using a username and password:</p> <div class="highlight"><pre class="highlight plaintext">$ vagrant cloud auth login +# ... +Vagrant Cloud username: +Vagrant Cloud password: +</pre></div> +<p>Check if the current user is authenticated:</p> <div class="highlight"><pre class="highlight plaintext">$ vagrant cloud auth login --check +You are already logged in. +</pre></div> +<p>Securely authenticate with Vagrant Cloud using a token:</p> <div class="highlight"><pre class="highlight plaintext">$ vagrant cloud auth login --token ABCD1234 +The token was successfully saved. +</pre></div> +<h2 id="cloud-auth-logout"> Cloud Auth Logout </h2> <p><strong>Command: <code>vagrant cloud auth logout</code></strong></p> <p>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.</p> <h2 id="cloud-auth-whomi"> Cloud Auth Whomi </h2> <p><strong>Command: <code>vagrant cloud auth whoami [TOKEN]</code></strong></p> <p>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.</p> <h1 id="cloud-box"> Cloud Box </h1> <p><strong>Command: <code>vagrant cloud box</code></strong></p> <p>The <code>cloud box</code> command is used to manage life cycle operations for all <code>box</code> entities on Vagrant Cloud.</p> <ul> <li> +<a href="#cloud-box-create"><code>create</code></a> </li> <li> +<a href="#cloud-box-delete"><code>delete</code></a> </li> <li> +<a href="#cloud-box-show"><code>show</code></a> </li> <li> +<a href="#cloud-box-update"><code>update</code></a> </li> </ul> <h2 id="cloud-box-create"> Cloud Box Create </h2> <p><strong>Command: <code>vagrant cloud box create ORGANIZATION/BOX-NAME</code></strong></p> <p>The box create command is used to create a new box entry on Vagrant Cloud.</p> <h3 id="options-1"> Options </h3> <ul> <li> +<a href="#description-description"><code>--description DESCRIPTION</code></a> - A full description of the box. Can be formatted with Markdown. </li> <li> +<a href="#short-description-description"><code>--short-description DESCRIPTION</code></a> - A short summary of the box. </li> <li> +<a href="#private"><code>--private</code></a> - Will make the new box private (Public by default) </li> </ul> <h2 id="cloud-box-delete"> Cloud Box Delete </h2> <p><strong>Command: <code>vagrant cloud box delete ORGANIZATION/BOX-NAME</code></strong></p> <p>The box delete command will <em>permanently</em> 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.</p> <h2 id="cloud-box-show"> Cloud Box Show </h2> <p><strong>Command: <code>vagrant cloud box show ORGANIZATION/BOX-NAME</code></strong></p> <p>The box show command will display information about the latest version for the given Vagrant box.</p> <h2 id="cloud-box-update"> Cloud Box Update </h2> <p><strong>Command: <code>vagrant cloud box update ORGANIZATION/BOX-NAME</code></strong></p> <p>The box update command will update an already created box on Vagrant Cloud with the given options.</p> <h3 id="options-2"> Options </h3> <ul> <li> +<a href="#description-description-1"><code>--description DESCRIPTION</code></a> - A full description of the box. Can be formatted with Markdown. </li> <li> +<a href="#short-description-description-1"><code>--short-description DESCRIPTION</code></a> - A short summary of the box. </li> <li> +<a href="#private-1"><code>--private</code></a> - Will make the new box private (Public by default) </li> </ul> <h1 id="cloud-provider"> Cloud Provider </h1> <p><strong>Command: <code>vagrant cloud provider</code></strong></p> <p>The <code>cloud provider</code> command is used to manage the life cycle operations for all <code>provider</code> entities on Vagrant Cloud.</p> <ul> <li> +<a href="#cloud-provider-create"><code>create</code></a> </li> <li> +<a href="#cloud-provider-delete"><code>delete</code></a> </li> <li> +<a href="#cloud-provider-update"><code>update</code></a> </li> <li> +<a href="#cloud-provider-upload"><code>upload</code></a> </li> </ul> <h2 id="cloud-provider-create"> Cloud Provider Create </h2> <p><strong>Command: <code>vagrant cloud provider create ORGANIZATION/BOX-NAME PROVIDER-NAME VERSION [URL]</code></strong></p> <p>The provider create command is used to create a new provider entry on Vagrant Cloud. The <code>url</code> argument is expected to be a remote URL that Vagrant Cloud can use to download the provider. If no <code>url</code> is specified, the provider entry can be updated later with a url or the <a href="#cloud-provider-upload">upload</a> command can be used to upload a Vagrant <a href="../boxes">box file</a>.</p> <h2 id="cloud-provider-delete"> Cloud Provider Delete </h2> <p><strong>Command: <code>vagrant cloud provider delete ORGANIZATION/BOX-NAME PROVIDER-NAME VERSION</code></strong></p> <p>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.</p> <h2 id="cloud-provider-update"> Cloud Provider Update </h2> <p><strong>Command: <code>vagrant cloud provider update ORGANIZATION/BOX-NAME PROVIDER-NAME VERSION [URL]</code></strong></p> <p>The provider update command will update an already created provider for a box on Vagrant Cloud with the given options.</p> <h2 id="cloud-provider-upload"> Cloud Provider Upload </h2> <p><strong>Command: <code>vagrant cloud provider upload ORGANIZATION/BOX-NAME PROVIDER-NAME VERSION BOX-FILE</code></strong></p> <p>The provider upload command will upload a Vagrant <a href="../boxes">box file</a> to Vagrant Cloud for the specified version and provider.</p> <h1 id="cloud-publish"> Cloud Publish </h1> <p><strong>Command: <code>vagrant cloud publish ORGANIZATION/BOX-NAME VERSION PROVIDER-NAME [PROVIDER-FILE]</code></strong></p> <p>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.</p> <h2 id="options-3"> Options </h2> <ul> <li> +<a href="#box-version-version"><code>--box-version VERSION</code></a> - Version to create for the box </li> <li> +<a href="#description-description-2"><code>--description DESCRIPTION</code></a> - A full description of the box. Can be formatted with Markdown. </li> <li> +<a href="#force"><code>--force</code></a> - Disables confirmation when creating or updating a box. </li> <li> +<a href="#short-description-description-2"><code>--short-description DESCRIPTION</code></a> - A short summary of the box. </li> <li> +<a href="#private-2"><code>--private</code></a> - Will make the new box private (Public by default) </li> <li> +<a href="#release"><code>--release</code></a> - Automatically releases the box after creation (Unreleased by default) </li> <li> +<a href="#url"><code>--url</code></a> - Valid remote URL to download the box file </li> <li> +<a href="#version-description-description"><code>--version-description DESCRIPTION</code></a> - Description of the version that will be created. </li> </ul> <h2 id="examples-1"> Examples </h2> <p>Creating a new box on Vagrant Cloud:</p> <div class="highlight"><pre class="highlight plaintext">$ 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 "Donwload 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 reall cool box to download and use +current_version: 1.0.0 +providers: virtualbox +</pre></div> +<h1 id="cloud-search"> Cloud Search </h1> <p><strong>Command: <code>vagrant cloud search QUERY</code></strong></p> <p>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.</p> <h2 id="options-4"> Options </h2> <ul> <li> +<a href="#json"><code>--json</code></a> - Format search results in JSON. </li> <li> +<a href="#page-page"><code>--page PAGE</code></a> - The page to display. Defaults to the first page of results. </li> <li> +<a href="#short"><code>--short</code></a> - Shows a simple list of box names for the results. </li> <li> +<a href="#order-order"><code>--order ORDER</code></a> - Order to display results. Can either be <code>desc</code> or <code>asc</code>. Defaults to <code>desc</code>. </li> <li> +<a href="#limit-limit"><code>--limit LIMIT</code></a> - Max number of search results to display. Defaults to 25. </li> <li> +<a href="#provider-provider"><code>--provider PROVIDER</code></a> - Filter search results to a single provider. </li> <li> +<a href="#sort-by-sort"><code>--sort-by SORT</code></a> - The field to sort results on. Can be <code>created</code>, <code>downloads</code> , or <code>updated</code>. Defaults to <code>downloads</code>. </li> </ul> <h2 id="examples-2"> Examples </h2> <p>If you are looking for a HashiCorp box:</p> <div class="highlight"><pre class="highlight plaintext">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 | ++-------------------------+---------+-----------+---------------------------------+ +</pre></div> +<h1 id="cloud-version"> Cloud Version </h1> <p><strong>Command: <code>vagrant cloud version</code></strong></p> <p>The <code>cloud version</code> command is used to manage life cycle operations for all <code>version</code> entities for a box on Vagrant Cloud.</p> <ul> <li> +<a href="#cloud-version-create"><code>create</code></a> </li> <li> +<a href="#cloud-version-delete"><code>delete</code></a> </li> <li> +<a href="#cloud-version-release"><code>release</code></a> </li> <li> +<a href="#cloud-version-revoke"><code>revoke</code></a> </li> <li> +<a href="#cloud-version-update"><code>update</code></a> </li> </ul> <h2 id="cloud-version-create"> Cloud Version Create </h2> <p><strong>Command: <code>vagrant cloud version create ORGANIZATION/BOX-NAME VERSION</code></strong></p> <p>The cloud create command creates a version entry for a box on Vagrant Cloud.</p> <h3 id="options-5"> Options </h3> <ul> <li> +<a href="#description-description-3"><code>--description DESCRIPTION</code></a> - Description of the version that will be created. </li> </ul> <h2 id="cloud-version-delete"> Cloud Version Delete </h2> <p><strong>Command: <code>vagrant cloud version delete ORGANIZATION/BOX-NAME VERSION</code></strong></p> <p>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.</p> <h2 id="cloud-version-release"> Cloud Version Release </h2> <p><strong>Command: <code>vagrant cloud version release ORGANIZATION/BOX-NAME VERSION</code></strong></p> <p>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.</p> <h2 id="cloud-version-revoke"> Cloud Version Revoke </h2> <p><strong>Command: <code>vagrant cloud version revoke ORGANIZATION/BOX-NAME VERSION</code></strong></p> <p>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.</p> <h2 id="cloud-version-update"> Cloud Version Update </h2> <p><strong>Command: <code>vagrant cloud version update ORGANIZATION/BOX-NAME VERSION</code></strong></p> <h3 id="options-6"> Options </h3> <ul> <li> +<a href="#description-description-4"><code>--description DESCRIPTION</code></a> - Description of the version that will be created. </li> </ul><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/cli/cloud.html" class="_attribution-link">https://www.vagrantup.com/docs/cli/cloud.html</a> + </p> +</div> diff --git a/devdocs/vagrant/cli%2Fconnect.html b/devdocs/vagrant/cli%2Fconnect.html new file mode 100644 index 00000000..20965f7f --- /dev/null +++ b/devdocs/vagrant/cli%2Fconnect.html @@ -0,0 +1,9 @@ +<h1 id="connect"> Connect </h1> <p><strong>Command: <code>vagrant connect NAME</code></strong></p> <p>The connect command complements the <a href="share">share command</a> by enabling access to shared environments. You can learn about all the details of Vagrant Share in the <a href="../share/index">Vagrant Share section</a>.</p> <p>The reference of available command-line flags to this command is available below.</p> <h2 id="options"> Options </h2> <ul> <li> +<p><a href="#disable-static-ip"><code>--disable-static-ip</code></a> - 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.</p> </li> <li> +<p><a href="#static-ip-ip"><code>--static-ip IP</code></a> - 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.</p> </li> <li> +<p><a href="#ssh"><code>--ssh</code></a> - Connects via SSH to an environment shared with <code>vagrant share --ssh</code>.</p> </li> </ul><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/cli/connect.html" class="_attribution-link">https://www.vagrantup.com/docs/cli/connect.html</a> + </p> +</div> diff --git a/devdocs/vagrant/cli%2Fdestroy.html b/devdocs/vagrant/cli%2Fdestroy.html new file mode 100644 index 00000000..29573042 --- /dev/null +++ b/devdocs/vagrant/cli%2Fdestroy.html @@ -0,0 +1,8 @@ +<h1 id="destroy"> Destroy </h1> <p><strong>Command: <code>vagrant destroy [name|id]</code></strong></p> <p>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.</p> <p>For linux-based guests, Vagrant uses the <code>shutdown</code> command to gracefully terminate the machine. Due to the varying nature of operating systems, the <code>shutdown</code> command may exist at many different locations in the guest's <code>$PATH</code>. It is the guest machine's responsibility to properly populate the <code>$PATH</code> with directory containing the <code>shutdown</code> command.</p> <h2 id="options"> Options </h2> <ul> <li> +<a href="#f"><code>-f</code></a> or <code>--force</code> - Do not ask for confirmation before destroying. </li> <li> +<a href="#no-parallel"><code>--[no-]parallel</code></a> - Destroys multiple machines in parallel if the provider supports it. Please consult the provider documentation to see if this feature is supported. </li> </ul> <blockquote class="alert alert-info"> <p>The <code>destroy</code> command does not remove a box that may have been installed on your computer during <code>vagrant up</code>. Thus, even if you run <code>vagrant destroy</code>, 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 <code>vagrant up</code> command, you need to use <code>vagrant box remove</code>.</p> <p>For more information, read about the <a href="box"><code>vagrant box remove</code></a> command.</p> </blockquote><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/cli/destroy.html" class="_attribution-link">https://www.vagrantup.com/docs/cli/destroy.html</a> + </p> +</div> diff --git a/devdocs/vagrant/cli%2Fglobal-status.html b/devdocs/vagrant/cli%2Fglobal-status.html new file mode 100644 index 00000000..61ceeaf9 --- /dev/null +++ b/devdocs/vagrant/cli%2Fglobal-status.html @@ -0,0 +1,7 @@ +<h1 id="global-status"> Global Status </h1> <p><strong>Command: <code>vagrant global-status</code></strong></p> <p>This command will tell you the state of all active Vagrant environments on the system for the currently logged in user.</p> <blockquote class="alert alert-warning" role="alert"> <p><strong>This command does not actively verify the state of machines</strong>, 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 <code>--prune</code> flag.</p> </blockquote> <p>The IDs in the output that look like <code>a1b2c3</code> can be used to control the Vagrant machine from anywhere on the system. Any Vagrant command that takes a target machine (such as <code>up</code>, <code>halt</code>, <code>destroy</code>) can be used with this ID to control it. For example: <code>vagrant destroy a1b2c3</code>.</p> <h2 id="options"> Options </h2> <ul> <li> +<a href="#prune"><code>--prune</code></a> - Prunes invalid entries from the list. This is much more time consuming than simply listing the entries. </li> </ul> <h2 id="environment-not-showing-up"> Environment Not Showing Up </h2> <p>If your environment is not showing up, you may have to do a <code>vagrant destroy</code> followed by a <code>vagrant up</code>.</p> <p>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.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/cli/global-status.html" class="_attribution-link">https://www.vagrantup.com/docs/cli/global-status.html</a> + </p> +</div> diff --git a/devdocs/vagrant/cli%2Fhalt.html b/devdocs/vagrant/cli%2Fhalt.html new file mode 100644 index 00000000..44eda701 --- /dev/null +++ b/devdocs/vagrant/cli%2Fhalt.html @@ -0,0 +1,7 @@ +<h1 id="halt"> Halt </h1> <p><strong>Command: <code>vagrant halt [name|id]</code></strong></p> <p>This command shuts down the running machine Vagrant is managing.</p> <p>Vagrant will first attempt to gracefully shut down the machine by running the guest OS shutdown mechanism. If this fails, or if the <code>--force</code> flag is specified, Vagrant will effectively just shut off power to the machine.</p> <p>For linux-based guests, Vagrant uses the <code>shutdown</code> command to gracefully terminate the machine. Due to the varying nature of operating systems, the <code>shutdown</code> command may exist at many different locations in the guest's <code>$PATH</code>. It is the guest machine's responsibility to properly populate the <code>$PATH</code> with directory containing the <code>shutdown</code> command.</p> <h2 id="options"> Options </h2> <ul> <li> +<a href="#f"><code>-f</code></a> or <code>--force</code> - Do not attempt to gracefully shut down the machine. This effectively pulls the power on the guest machine. </li> </ul><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/cli/halt.html" class="_attribution-link">https://www.vagrantup.com/docs/cli/halt.html</a> + </p> +</div> diff --git a/devdocs/vagrant/cli%2Findex.html b/devdocs/vagrant/cli%2Findex.html new file mode 100644 index 00000000..3d96c3b7 --- /dev/null +++ b/devdocs/vagrant/cli%2Findex.html @@ -0,0 +1,6 @@ +<h1 id="command-line-interface"> Command-Line Interface </h1> <p>Almost all interaction with Vagrant is done through the command-line interface.</p> <p>The interface is available using the <code>vagrant</code> command, and comes installed with Vagrant automatically. The <code>vagrant</code> command in turn has many subcommands, such as <code>vagrant up</code>, <code>vagrant destroy</code>, etc.</p> <p>If you run <code>vagrant</code> by itself, help will be displayed showing all available subcommands. In addition to this, you can run any Vagrant command with the <code>-h</code> flag to output help about that specific command. For example, try running <code>vagrant init -h</code>. 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.</p> <p>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.</p> <p>You may also wish to consult the <a href="../other/environmental-variables">documentation</a> regarding the environmental variables that can be used to configure and control Vagrant in a global way.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/cli/" class="_attribution-link">https://www.vagrantup.com/docs/cli/</a> + </p> +</div> diff --git a/devdocs/vagrant/cli%2Finit.html b/devdocs/vagrant/cli%2Finit.html new file mode 100644 index 00000000..0b074a05 --- /dev/null +++ b/devdocs/vagrant/cli%2Finit.html @@ -0,0 +1,20 @@ +<h1 id="init"> Init </h1> <p><strong>Command: <code>vagrant init [name [url]]</code></strong></p> <p>This initializes the current directory to be a Vagrant environment by creating an initial <a href="../vagrantfile/index">Vagrantfile</a> if one does not already exist.</p> <p>If a first argument is given, it will prepopulate the <code>config.vm.box</code> setting in the created Vagrantfile.</p> <p>If a second argument is given, it will prepopulate the <code>config.vm.box_url</code> setting in the created Vagrantfile.</p> <h2 id="options"> Options </h2> <ul> <li> +<p><a href="#box-version"><code>--box-version</code></a> - (Optional) The box version or box version constraint to add to the <code>Vagrantfile</code>.</p> </li> <li> +<p><a href="#force"><code>--force</code></a> - If specified, this command will overwrite any existing <code>Vagrantfile</code>.</p> </li> <li> +<p><a href="#minimal"><code>--minimal</code></a> - If specified, a minimal Vagrantfile will be created. This Vagrantfile does not contain the instructional comments that the normal Vagrantfile contains.</p> </li> <li> +<p><a href="#output-file"><code>--output FILE</code></a> - This will output the Vagrantfile to the given file. If this is "-", the Vagrantfile will be sent to stdout.</p> </li> <li> +<p><a href="#template-file"><code>--template FILE</code></a> - Provide a custom ERB template for generating the Vagrantfile.</p> </li> </ul> <h2 id="examples"> Examples </h2> <p>Create a base Vagrantfile:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ vagrant init hashicorp/precise64 +</pre></div> +<p>Create a minimal Vagrantfile (no comments or helpers):</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ vagrant init -m hashicorp/precise64 +</pre></div> +<p>Create a new Vagrantfile, overwriting the one at the current path:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ vagrant init -f hashicorp/precise64 +</pre></div> +<p>Create a Vagrantfile with the specific box, from the specific box URL:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ vagrant init my-company-box https://boxes.company.com/my-company.box +</pre></div> +<p>Create a Vagrantfile, locking the box to a version constraint:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ vagrant init --box-version '> 0.1.5' hashicorp/precise64 +</pre></div><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/cli/init.html" class="_attribution-link">https://www.vagrantup.com/docs/cli/init.html</a> + </p> +</div> diff --git a/devdocs/vagrant/cli%2Flogin.html b/devdocs/vagrant/cli%2Flogin.html new file mode 100644 index 00000000..ad5485fb --- /dev/null +++ b/devdocs/vagrant/cli%2Flogin.html @@ -0,0 +1,19 @@ +<h1 id="login"> Login </h1> <p><strong>Command: <code>vagrant login</code></strong></p> <p>The login command is used to authenticate with the <a href="https://www.vagrantup.com/docs/vagrant-cloud">HashiCorp's Vagrant Cloud</a> server. Logging in is only necessary if you are accessing protected boxes or using <a href="../share/index">Vagrant Share</a>.</p> <p><strong>Logging in is not a requirement to use Vagrant.</strong> The vast majority of Vagrant does <em>not</em> require a login. Only certain features such as protected boxes or <a href="../share/index">Vagrant Share</a> require a login.</p> <p>The reference of available command-line flags to this command is available below.</p> <h2 id="options"> Options </h2> <ul> <li> +<p><a href="#check"><code>--check</code></a> - 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.</p> </li> <li> +<p><a href="#logout"><code>--logout</code></a> - 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.</p> </li> <li> +<p><a href="#token"><code>--token</code></a> - 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.</p> </li> </ul> <h2 id="examples"> Examples </h2> <p>Securely authenticate to Vagrant Cloud using a username and password:</p> <div class="highlight"><pre class="highlight plaintext">$ vagrant login +# ... +Vagrant Cloud username: +Vagrant Cloud password: +</pre></div> +<p>Check if the current user is authenticated:</p> <div class="highlight"><pre class="highlight plaintext">$ vagrant login --check +You are already logged in. +</pre></div> +<p>Securely authenticate with Vagrant Cloud using a token:</p> <div class="highlight"><pre class="highlight plaintext">$ vagrant login --token ABCD1234 +The token was successfully saved. +</pre></div><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/cli/login.html" class="_attribution-link">https://www.vagrantup.com/docs/cli/login.html</a> + </p> +</div> diff --git a/devdocs/vagrant/cli%2Fmachine-readable.html b/devdocs/vagrant/cli%2Fmachine-readable.html new file mode 100644 index 00000000..1af06e73 --- /dev/null +++ b/devdocs/vagrant/cli%2Fmachine-readable.html @@ -0,0 +1,22 @@ +<h1 id="machine-readable-output"> Machine Readable Output </h1> <p>Every Vagrant command accepts a <code>--machine-readable</code> flag which enables machine readable output mode. In this mode, the output to the terminal is replaced with machine-friendly output.</p> <p>This mode makes it easy to programmatically execute Vagrant and read data out of it. This output format is protected by our <a href="../installation/backwards-compatibility">backwards compatibility</a> 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.</p> <blockquote class="alert alert-warning"> <p><strong>Advanced topic!</strong> 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.</p> </blockquote> +<h2 id="work-in-progress"> Work-In-Progress </h2> <p>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.</p> <p>In this case, we ask that you please <a href="https://github.com/hashicorp/vagrant/issues">open an issue</a> requesting that certain information become available. We will most likely add it!</p> <h2 id="format"> Format </h2> <p>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.</p> <p>The format is:</p> <div class="highlight"><pre class="highlight plaintext">timestamp,target,type,data... +</pre></div> +<p>Each component is explained below:</p> <ul> <li> +<p><strong>timestamp</strong> is a Unix timestamp in UTC of when the message was printed.</p> </li> <li> +<p><strong>target</strong> 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.</p> </li> <li> +<p><strong>type</strong> is the type of machine-readable message being outputted. There are a set of standard types which are covered later.</p> </li> <li> +<p><strong>data</strong> 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.</p> </li> </ul> <p>Within the format, if data contains a comma, it is replaced with <code>%!(VAGRANT_COMMA)</code>. This was preferred over an escape character such as \' because it is more friendly to tools like awk.</p> <p>Newlines within the format are replaced with their respective standard escape sequence. Newlines become a literal <code>\n</code> within the output. Carriage returns become a literal <code>\r</code>.</p> <h2 id="types"> Types </h2> <p>This section documents all the available types that may be outputted with the machine-readable output.</p> <table class="table table-hover table-bordered mr-types"> <p><thead> <tr> <th class="mr-type">Type</th> <th>Description</th> </tr> </thead></p> +<tr> <td>box-name</td> <td> Name of a box installed into Vagrant. </td> </tr> +<tr> <td>box-provider</td> <td> Provider for an installed box. </td> </tr> +<tr> <td>cli-command</td> <td> A subcommand of <code>vagrant</code> that is available. </td> </tr> +<tr> <td>error-exit</td> <td> An error occurred that caused Vagrant to exit. This contains that error. Contains two data elements: type of error, error message. </td> </tr> +<tr> <td>provider-name</td> <td> The provider name of the target machine. <span class="label">targeted</span> </td> </tr> +<tr> <td>ssh-config</td> <td> The OpenSSH compatible SSH config for a machine. This is usually the result of the "ssh-config" command. <span class="label">targeted</span> </td> </tr> +<tr> <td>state</td> <td> The state ID of the target machine. <span class="label">targeted</span> </td> </tr> +<tr> <td>state-human-long</td> <td> Human-readable description of the state of the machine. This is the long version, and may be a paragraph or longer. <span class="label">targeted</span> </td> </tr> +<tr> <td>state-human-short</td> <td> Human-readable description of the state of the machine. This is the short version, limited to at most a sentence. <span class="label">targeted</span> </td> </tr> </table><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/cli/machine-readable.html" class="_attribution-link">https://www.vagrantup.com/docs/cli/machine-readable.html</a> + </p> +</div> diff --git a/devdocs/vagrant/cli%2Fnon-primary.html b/devdocs/vagrant/cli%2Fnon-primary.html new file mode 100644 index 00000000..39c9ccea --- /dev/null +++ b/devdocs/vagrant/cli%2Fnon-primary.html @@ -0,0 +1,11 @@ +<h1 id="more-commands"> More Commands </h1> <p>In addition to the commands listed in the sidebar and shown in <code>vagrant -h</code>, 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".</p> <p>You can view all subcommands, including the non-primary subcommands, by running <code>vagrant list-commands</code>, which itself is a non-primary subcommand!</p> <p>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 <em>run</em> the non-primary subcommands. They're executed just like any other subcommand: <code>vagrant COMMAND</code>.</p> <p>The list of non-primary commands is below. Click on any command to learn more about it.</p> <ul> <li> +<a href="../docker/commands">docker-exec</a> </li> <li> +<a href="../docker/commands">docker-logs</a> </li> <li> +<a href="../docker/commands">docker-run</a> </li> <li> +<a href="rsync">rsync</a> </li> <li> +<a href="rsync-auto">rsync-auto</a> </li> </ul><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/cli/non-primary.html" class="_attribution-link">https://www.vagrantup.com/docs/cli/non-primary.html</a> + </p> +</div> diff --git a/devdocs/vagrant/cli%2Fpackage.html b/devdocs/vagrant/cli%2Fpackage.html new file mode 100644 index 00000000..c64962d6 --- /dev/null +++ b/devdocs/vagrant/cli%2Fpackage.html @@ -0,0 +1,10 @@ +<h1 id="package"> Package </h1> <p><strong>Command: <code>vagrant package [name|id]</code></strong></p> <p>This packages a currently running <em>VirtualBox</em> or <em>Hyper-V</em> environment into a re-usable <a href="../boxes">box</a>. This command can only be used with other <a href="../providers/index">providers</a> based on the provider implementation and if the provider supports it.</p> <h2 id="options"> Options </h2> <ul> <li> +<p><a href="#base-name"><code>--base NAME</code></a> - Instead of packaging a VirtualBox machine that Vagrant manages, this will package a VirtualBox machine that VirtualBox manages. <code>NAME</code> should be the name or UUID of the machine from the VirtualBox GUI. Currently this option is only available for VirtualBox.</p> </li> <li> +<p><a href="#output-name"><code>--output NAME</code></a> - The resulting package will be saved as <code>NAME</code>. By default, it will be saved as <code>package.box</code>.</p> </li> <li> +<p><a href="#include-x-y-z"><code>--include x,y,z</code></a> - Additional files will be packaged with the box. These can be used by a packaged Vagrantfile (documented below) to perform additional tasks.</p> </li> <li> +<p><a href="#vagrantfile-file"><code>--vagrantfile FILE</code></a> - Packages a Vagrantfile with the box, that is loaded as part of the <a href="../vagrantfile/index#load-order">Vagrantfile load order</a> when the resulting box is used.</p> </li> </ul> <blockquote class="alert alert-info"> <p><strong>A common misconception</strong> is that the <code>--vagrantfile</code> option will package a Vagrantfile that is used when <code>vagrant init</code> 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 <a href="../vagrantfile/index#load-order">Vagrantfile load order</a>.</p> </blockquote><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/cli/package.html" class="_attribution-link">https://www.vagrantup.com/docs/cli/package.html</a> + </p> +</div> diff --git a/devdocs/vagrant/cli%2Fplugin.html b/devdocs/vagrant/cli%2Fplugin.html new file mode 100644 index 00000000..3156c071 --- /dev/null +++ b/devdocs/vagrant/cli%2Fplugin.html @@ -0,0 +1,36 @@ +<h1 id="plugin"> Plugin </h1> <p><strong>Command: <code>vagrant plugin</code></strong></p> <p>This is the command used to manage <a href="../plugins/index">plugins</a>.</p> <p>The main functionality of this command is exposed via another level of subcommands:</p> <ul> <li> +<a href="#plugin-expunge"><code>expunge</code></a> </li> <li> +<a href="#plugin-install"><code>install</code></a> </li> <li> +<a href="#plugin-license"><code>license</code></a> </li> <li> +<a href="#plugin-list"><code>list</code></a> </li> <li> +<a href="#plugin-repair"><code>repair</code></a> </li> <li> +<a href="#plugin-uninstall"><code>uninstall</code></a> </li> <li> +<a href="#plugin-update"><code>update</code></a> </li> </ul> <h1 id="plugin-expunge"> Plugin Expunge </h1> <p><strong>Command: <code>vagrant plugin expunge</code></strong></p> <p>This removes all user installed plugin information. All plugin gems, their dependencies, and the <code>plugins.json</code> file are removed. This command provides a simple mechanism to fully remove all user installed custom plugins.</p> <p>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:</p> <div class="highlight"><pre class="highlight shell" data-language="shell"># Delete all plugins and reinstall +$ vagrant plugin expunge --reinstall +</pre></div> +<p>This command accepts optional command-line flags:</p> <ul> <li> +<a href="#force"><code>--force</code></a> - Do not prompt for confirmation prior to removal </li> <li> +<a href="#global-only"><code>--global-only</code></a> - Only expunge global plugins </li> <li> +<a href="#local"><code>--local</code></a> - Include plugins in local project </li> <li> +<a href="#local-only"><code>--local-only</code></a> - Only expunge local project plugins </li> <li> +<a href="#reinstall"><code>--reinstall</code></a> - Attempt to reinstall plugins after removal </li> </ul> <h1 id="plugin-install"> Plugin Install </h1> <p><strong>Command: <code>vagrant plugin install <name>...</code></strong></p> <p>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 <a href="https://rubygems.org">RubyGems</a>. This command will also update a plugin if it is already installed, but you can also use <code>vagrant plugin update</code> for that.</p> <div class="highlight"><pre class="highlight shell" data-language="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 +</pre></div> +<p>If multiple names are specified, multiple plugins will be installed. If flags are given below, the flags will apply to <em>all</em> plugins being installed by the current command invocation.</p> <p>If the plugin is already installed, this command will reinstall it with the latest version available.</p> <p>This command accepts optional command-line flags:</p> <ul> <li> +<p><a href="#entry-point-entrypoint"><code>--entry-point ENTRYPOINT</code></a> - 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.</p> </li> <li> +<p><a href="#local-1"><code>--local</code></a> - Install plugin to the local Vagrant project only.</p> </li> <li> +<p><a href="#plugin-clean-sources"><code>--plugin-clean-sources</code></a> - 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.</p> </li> <li> +<p><a href="#plugin-source-source"><code>--plugin-source SOURCE</code></a> - 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.</p> </li> <li> +<p><a href="#plugin-version-version"><code>--plugin-version VERSION</code></a> - 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).</p> </li> </ul> <h1 id="plugin-license"> Plugin License </h1> <p><strong>Command: <code>vagrant plugin license <name> <license-file></code></strong></p> <p>This command installs a license for a proprietary Vagrant plugin, such as the <a href="../vmware">VMware Fusion provider</a>.</p> <h1 id="plugin-list"> Plugin List </h1> <p><strong>Command: <code>vagrant plugin list</code></strong></p> <p>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.</p> <p>This command accepts optional command-line flags:</p> <ul> <li> +<a href="#local-2"><code>--local</code></a> - Include local project plugins. </li> </ul> <h1 id="plugin-repair"> Plugin Repair </h1> <p>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 <code>plugins.json</code> data file. Vagrant can attempt to automatically repair the problem.</p> <p>If automatic repair is not successful, refer to the <a href="#plugin-expunge">expunge</a> command</p> <p>This command accepts optional command-line flags:</p> <ul> <li> +<a href="#local-3"><code>--local</code></a> - Repair local project plugins. </li> </ul> <h1 id="plugin-uninstall"> Plugin Uninstall </h1> <p><strong>Command: <code>vagrant plugin uninstall <name> [<name2> <name3> ...]</code></strong></p> <p>This uninstalls the plugin with the given name. Any dependencies of the plugin will also be uninstalled assuming no other plugin needs them.</p> <p>If multiple plugins are given, multiple plugins will be uninstalled.</p> <p>This command accepts optional command-line flags:</p> <ul> <li> +<a href="#local-4"><code>--local</code></a> - Uninstall plugin from local project. </li> </ul> <h1 id="plugin-update"> Plugin Update </h1> <p><strong>Command: <code>vagrant plugin update [<name>]</code></strong></p> <p>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 <code>vagrant plugin install</code>.</p> <p>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.</p> <p>This command accepts optional command-line flags:</p> <ul> <li> +<a href="#local-5"><code>--local</code></a> - Update plugin from local project. </li> </ul><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/cli/plugin.html" class="_attribution-link">https://www.vagrantup.com/docs/cli/plugin.html</a> + </p> +</div> diff --git a/devdocs/vagrant/cli%2Fport.html b/devdocs/vagrant/cli%2Fport.html new file mode 100644 index 00000000..86afbecc --- /dev/null +++ b/devdocs/vagrant/cli%2Fport.html @@ -0,0 +1,16 @@ +<h1 id="port"> Port </h1> <p><strong>Command: <code>vagrant port [name|id]</code></strong></p> <p>The port command displays the full list of guest ports mapped to the host machine ports:</p> <div class="highlight"><pre class="highlight plaintext">$ vagrant port + 22 (guest) => 2222 (host) + 80 (guest) => 8080 (host) +</pre></div> +<p>In a multi-machine Vagrantfile, the name of the machine must be specified:</p> <div class="highlight"><pre class="highlight plaintext">$ vagrant port my-machine +</pre></div> +<h2 id="options"> Options </h2> <ul> <li> +<p><a href="#guest-port"><code>--guest PORT</code></a> - 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:</p> <div class="highlight"><pre class="highlight plaintext">$ ssh -p $(vagrant port --guest 22) +</pre></div> +</li> <li> +<p><a href="#machine-readable"><code>--machine-readable</code></a> - This tells Vagrant to display machine-readable output instead of the human-friendly output. More information is available in the <a href="machine-readable">machine-readable output</a> documentation.</p> </li> </ul><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/cli/port.html" class="_attribution-link">https://www.vagrantup.com/docs/cli/port.html</a> + </p> +</div> diff --git a/devdocs/vagrant/cli%2Fpowershell.html b/devdocs/vagrant/cli%2Fpowershell.html new file mode 100644 index 00000000..88bfedfb --- /dev/null +++ b/devdocs/vagrant/cli%2Fpowershell.html @@ -0,0 +1,7 @@ +<h1 id="powershell"> PowerShell </h1> <p><strong>Command: <code>vagrant powershell</code></strong></p> <p>This will open a PowerShell prompt on the host into a running Vagrant guest machine.</p> <p>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.</p> <h2 id="options"> Options </h2> <ul> <li> +<a href="#c-command"><code>-c COMMAND</code></a> or <code>--command COMMAND</code> - This executes a single PowerShell command, prints out the stdout and stderr, and exits. </li> </ul><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/cli/powershell.html" class="_attribution-link">https://www.vagrantup.com/docs/cli/powershell.html</a> + </p> +</div> diff --git a/devdocs/vagrant/cli%2Fprovision.html b/devdocs/vagrant/cli%2Fprovision.html new file mode 100644 index 00000000..30089253 --- /dev/null +++ b/devdocs/vagrant/cli%2Fprovision.html @@ -0,0 +1,7 @@ +<h1 id="provision"> Provision </h1> <p><strong>Command: <code>vagrant provision [vm-name]</code></strong></p> <p>Runs any configured <a href="../provisioning/index">provisioners</a> against the running Vagrant managed machine.</p> <p>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 <code>vagrant provision</code>, and check for the desired results. Rinse and repeat.</p> <h1 id="options"> Options </h1> <ul> <li> +<a href="#provision-with-x-y-z"><code>--provision-with x,y,z</code></a> - This will only run the given provisioners. For example, if you have a <code>:shell</code> and <code>:chef_solo</code> provisioner and run <code>vagrant provision --provision-with shell</code>, only the shell provisioner will be run. </li> </ul><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/cli/provision.html" class="_attribution-link">https://www.vagrantup.com/docs/cli/provision.html</a> + </p> +</div> diff --git a/devdocs/vagrant/cli%2Frdp.html b/devdocs/vagrant/cli%2Frdp.html new file mode 100644 index 00000000..9fef1627 --- /dev/null +++ b/devdocs/vagrant/cli%2Frdp.html @@ -0,0 +1,10 @@ +<h1 id="rdp"> RDP </h1> <p><strong>Command: <code>vagrant rdp</code></strong></p> <p>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.</p> <h2 id="raw-arguments"> Raw Arguments </h2> <p>You can pass raw arguments through to your RDP client on the command-line by appending it after a <code>--</code>. Vagrant just passes these through. For example:</p> <div class="highlight"><pre class="highlight plaintext">$ vagrant rdp -- /span +</pre></div> +<p>The above command on Windows will execute <code>mstsc.exe /span config.rdp</code>, allowing your RDP to span multiple desktops.</p> <p>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 <em>must</em> quote multiple arguments. For example:</p> <div class="highlight"><pre class="highlight plaintext">$ vagrant rdp -- "screen mode id:i:0" "other config:s:value" +</pre></div> +<p>Note that as of the publishing of this guide, the Microsoft RDP Client for Mac does <em>not</em> 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!</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/cli/rdp.html" class="_attribution-link">https://www.vagrantup.com/docs/cli/rdp.html</a> + </p> +</div> diff --git a/devdocs/vagrant/cli%2Freload.html b/devdocs/vagrant/cli%2Freload.html new file mode 100644 index 00000000..4966cd62 --- /dev/null +++ b/devdocs/vagrant/cli%2Freload.html @@ -0,0 +1,8 @@ +<h1 id="reload"> Reload </h1> <p><strong>Command: <code>vagrant reload [name|id]</code></strong></p> <p>The equivalent of running a <a href="halt">halt</a> followed by an <a href="up">up</a>.</p> <p>This command is usually required for changes made in the Vagrantfile to take effect. After making any modifications to the Vagrantfile, a <code>reload</code> should be called.</p> <p>The configured provisioners will not run again, by default. You can force the provisioners to re-run by specifying the <code>--provision</code> flag.</p> <h1 id="options"> Options </h1> <ul> <li> +<p><a href="#provision"><code>--provision</code></a> - Force the provisioners to run.</p> </li> <li> +<p><a href="#provision-with-x-y-z"><code>--provision-with x,y,z</code></a> - This will only run the given provisioners. For example, if you have a <code>:shell</code> and <code>:chef_solo</code> provisioner and run <code>vagrant reload --provision-with shell</code>, only the shell provisioner will be run.</p> </li> </ul><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/cli/reload.html" class="_attribution-link">https://www.vagrantup.com/docs/cli/reload.html</a> + </p> +</div> diff --git a/devdocs/vagrant/cli%2Fresume.html b/devdocs/vagrant/cli%2Fresume.html new file mode 100644 index 00000000..6e7e85d9 --- /dev/null +++ b/devdocs/vagrant/cli%2Fresume.html @@ -0,0 +1,8 @@ +<h1 id="resume"> Resume </h1> <p><strong>Command: <code>vagrant resume [name|id]</code></strong></p> <p>This resumes a Vagrant managed machine that was previously suspended, perhaps with the <a href="suspend">suspend command</a>.</p> <p>The configured provisioners will not run again, by default. You can force the provisioners to re-run by specifying the <code>--provision</code> flag.</p> <h1 id="options"> Options </h1> <ul> <li> +<p><a href="#provision"><code>--provision</code></a> - Force the provisioners to run.</p> </li> <li> +<p><a href="#provision-with-x-y-z"><code>--provision-with x,y,z</code></a> - This will only run the given provisioners. For example, if you have a <code>:shell</code> and <code>:chef_solo</code> provisioner and run <code>vagrant provision --provision-with shell</code>, only the shell provisioner will be run.</p> </li> </ul><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/cli/resume.html" class="_attribution-link">https://www.vagrantup.com/docs/cli/resume.html</a> + </p> +</div> diff --git a/devdocs/vagrant/cli%2Frsync-auto.html b/devdocs/vagrant/cli%2Frsync-auto.html new file mode 100644 index 00000000..e47773d2 --- /dev/null +++ b/devdocs/vagrant/cli%2Frsync-auto.html @@ -0,0 +1,7 @@ +<h1 id="rsync-auto"> rsync-auto </h1> <p><strong>Command: <code>vagrant rsync-auto</code></strong></p> <p>This command watches all local directories of any <a href="../synced-folders/rsync">rsync synced folders</a> and automatically initiates an rsync transfer when changes are detected. This command does not exit until an interrupt is received.</p> <p>The change detection is optimized to use platform-specific APIs to listen for filesystem changes, and does not simply poll the directory.</p> <h2 id="options"> Options </h2> <ul> <li> +<a href="#no-poll"><code>--[no-]poll</code></a> - 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 <code>rsync-auto</code> <em>much</em> slower. By default, polling is disabled. </li> </ul> <h2 id="machine-state-changes"> Machine State Changes </h2> <p>The <code>rsync-auto</code> command does not currently handle machine state changes gracefully. For example, if you start the <code>rsync-auto</code> command, then halt the guest machine, then make changes to some files, then boot it back up, <code>rsync-auto</code> will not attempt to resync.</p> <p>To ensure that the command works properly, you should start <code>rsync-auto</code> only when the machine is running, and shut it down before any machine state changes.</p> <p>You can always force a resync with the <a href="rsync">rsync</a> command.</p> <h2 id="vagrantfile-changes"> Vagrantfile Changes </h2> <p>If you change or move your Vagrantfile, the <code>rsync-auto</code> 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 <code>rsync-auto</code> command will either not pick up the changes or may begin experiencing strange behavior.</p> <p>Before making any such changes, it is recommended that you turn off <code>rsync-auto</code>, then restart it afterwards.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/cli/rsync-auto.html" class="_attribution-link">https://www.vagrantup.com/docs/cli/rsync-auto.html</a> + </p> +</div> diff --git a/devdocs/vagrant/cli%2Frsync.html b/devdocs/vagrant/cli%2Frsync.html new file mode 100644 index 00000000..9228d232 --- /dev/null +++ b/devdocs/vagrant/cli%2Frsync.html @@ -0,0 +1,6 @@ +<h1 id="rsync"> Rsync </h1> <p><strong>Command: <code>vagrant rsync</code></strong></p> <p>This command forces a re-sync of any <a href="../synced-folders/rsync">rsync synced folders</a>.</p> <p>Note that if you change any settings within the rsync synced folders such as exclude paths, you will need to <code>vagrant reload</code> before this command will pick up those changes.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/cli/rsync.html" class="_attribution-link">https://www.vagrantup.com/docs/cli/rsync.html</a> + </p> +</div> diff --git a/devdocs/vagrant/cli%2Fshare.html b/devdocs/vagrant/cli%2Fshare.html new file mode 100644 index 00000000..7055ffa9 --- /dev/null +++ b/devdocs/vagrant/cli%2Fshare.html @@ -0,0 +1,13 @@ +<h1 id="share"> Share </h1> <p><strong>Command: <code>vagrant share</code></strong></p> <p>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.</p> <p>You can learn about all the details of Vagrant Share in the <a href="../share/index">Vagrant Share section</a>.</p> <p>The reference of available command-line flags to this command is available below.</p> <h2 id="options"> Options </h2> <ul> <li> +<p><a href="#disable-http"><code>--disable-http</code></a> - 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 <code>vagrant connect</code>.</p> </li> <li> +<p><a href="#http-port"><code>--http PORT</code></a> - 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 <code>--disable-http</code> is set.</p> </li> <li> +<p><a href="#https-port"><code>--https PORT</code></a> - 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 <code>--disable-http</code> is set.</p> </li> <li> +<p><a href="#ssh"><code>--ssh</code></a> - Enables SSH sharing (more information below). By default, this is not enabled.</p> </li> <li> +<p><a href="#ssh-no-password"><code>--ssh-no-password</code></a> - Disables the encryption of the SSH keypair created when SSH sharing is enabled.</p> </li> <li> +<p><a href="#ssh-port-port"><code>--ssh-port PORT</code></a> - The port of the SSH server running in the Vagrant environment. By default, Vagrant will attempt to find this for you.</p> </li> <li> +<p><a href="#ssh-once"><code>--ssh-once</code></a> - Allows SSH access only once. After the first attempt to connect via SSH to the Vagrant environment, the generated keypair is destroyed.</p> </li> </ul><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/cli/share.html" class="_attribution-link">https://www.vagrantup.com/docs/cli/share.html</a> + </p> +</div> diff --git a/devdocs/vagrant/cli%2Fsnapshot.html b/devdocs/vagrant/cli%2Fsnapshot.html new file mode 100644 index 00000000..97182227 --- /dev/null +++ b/devdocs/vagrant/cli%2Fsnapshot.html @@ -0,0 +1,15 @@ +<h1 id="snapshot"> Snapshot </h1> <p><strong>Command: <code>vagrant snapshot</code></strong></p> <p>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.</p> <p>Snapshotting is not supported by every provider. If it is not supported, Vagrant will give you an error message.</p> <p>The main functionality of this command is exposed via even more subcommands:</p> <ul> <li> +<a href="#snapshot-push"><code>push</code></a> </li> <li> +<a href="#snapshot-pop"><code>pop</code></a> </li> <li> +<a href="#snapshot-save"><code>save</code></a> </li> <li> +<a href="#snapshot-restore"><code>restore</code></a> </li> <li> +<a href="#snapshot-list"><code>list</code></a> </li> <li> +<a href="#snapshot-delete"><code>delete</code></a> </li> </ul> <h1 id="snapshot-push"> Snapshot Push </h1> <p><strong>Command: <code>vagrant snapshot push</code></strong></p> <p>This takes a snapshot and pushes it onto the snapshot stack.</p> <p>This is a shorthand for <code>vagrant snapshot save</code> where you do not need to specify a name. When you call the inverse <code>vagrant snapshot pop</code>, it will restore the pushed state.</p> <blockquote class="alert alert-warning" role="alert"> <p><strong>Warning:</strong> If you are using <code>push</code> and <code>pop</code>, avoid using <code>save</code> and <code>restore</code> which are unsafe to mix.</p> </blockquote> <h1 id="snapshot-pop"> Snapshot Pop </h1> <p><strong>Command: <code>vagrant snapshot pop</code></strong></p> <p>This command is the inverse of <code>vagrant snapshot push</code>: it will restore the pushed state.</p> <h2 id="options"> Options </h2> <ul> <li> +<p><a href="#no-provision"><code>--[no-]provision</code></a> - Force the provisioners to run (or prevent them from doing so).</p> </li> <li> +<p><a href="#no-delete"><code>--no-delete</code></a> - Prevents deletion of the snapshot after restoring (so that you can restore to the same point again later).</p> </li> </ul> <h1 id="snapshot-save"> Snapshot Save </h1> <p><strong>Command: <code>vagrant snapshot save [vm-name] NAME</code></strong></p> <p>This command saves a new named snapshot. If this command is used, the <code>push</code> and <code>pop</code> subcommands cannot be safely used.</p> <h1 id="snapshot-restore"> Snapshot Restore </h1> <p><strong>Command: <code>vagrant snapshot restore [vm-name] NAME</code></strong></p> <p>This command restores the named snapshot.</p> <ul> <li> +<a href="#no-provision-1"><code>--[no-]provision</code></a> - Force the provisioners to run (or prevent them from doing so). </li> </ul> <h1 id="snapshot-list"> Snapshot List </h1> <p><strong>Command: <code>vagrant snapshot list</code></strong></p> <p>This command will list all the snapshots taken.</p> <h1 id="snapshot-delete"> Snapshot Delete </h1> <p><strong>Command: <code>vagrant snapshot delete NAME</code></strong></p> <p>This command will delete the named snapshot.</p> <p>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.</p> <p>This command is typically <em>much faster</em> 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.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/cli/snapshot.html" class="_attribution-link">https://www.vagrantup.com/docs/cli/snapshot.html</a> + </p> +</div> diff --git a/devdocs/vagrant/cli%2Fssh.html b/devdocs/vagrant/cli%2Fssh.html new file mode 100644 index 00000000..30b8bbea --- /dev/null +++ b/devdocs/vagrant/cli%2Fssh.html @@ -0,0 +1,65 @@ +<h1 id="ssh"> SSH </h1> <p><strong>Command: <code>vagrant ssh [name|id] [-- extra_ssh_args]</code></strong></p> <p>This will SSH into a running Vagrant machine and give you access to a shell.</p> <p>On a simple vagrant project, the instance created will be named default.</p> <p>Vagrant will ssh into this instance without the instance name:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ 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. +</pre></div> +<p>Or you could use the name:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ 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. +$ +</pre></div> +<p>On multi-machine setups, you can login to each vm using the name as displayed on <code>vagrant status</code></p> <div class="highlight"><pre class="highlight shell" data-language="shell"> $ 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@precise64:~$ 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@precise64:~$ logout +Connection to 127.0.0.1 closed. +$ +</pre></div> +<p>On a system with machines running from different projects, you could use the id as listed in <code>vagrant global-status</code></p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ 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@precise64:~$ logout +Connection to 127.0.0.1 closed. +$ +</pre></div> +<p>If a <code>--</code> (two hyphens) are found on the command line, any arguments after this are passed directly into the <code>ssh</code> executable. This allows you to pass any arbitrary commands to do things such as reverse tunneling down into the <code>ssh</code> program.</p> <h2 id="options"> Options </h2> <ul> <li> +<p><a href="#c-command"><code>-c COMMAND</code></a> or <code>--command COMMAND</code> - This executes a single SSH command, prints out the stdout and stderr, and exits.</p> </li> <li> +<p><a href="#p"><code>-p</code></a> or <code>--plain</code> - This does an SSH without authentication, leaving authentication up to the user.</p> </li> </ul> <h2 id="ssh-client-usage"> SSH client usage </h2> <p>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.</p> <p>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.</p> <h2 id="background-execution"> Background Execution </h2> <p>If the command you specify runs in the background (such as appending a <code>&</code> 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.</p> <p>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 <code>nohup</code> command.</p> <h2 id="pageant-on-windows"> Pageant on Windows </h2> <p>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 <code>vagrant ssh</code> command.</p> <p>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 <a href="https://github.com/cuviper/ssh-pageant">ssh-pageant</a>.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/cli/ssh.html" class="_attribution-link">https://www.vagrantup.com/docs/cli/ssh.html</a> + </p> +</div> diff --git a/devdocs/vagrant/cli%2Fssh_config.html b/devdocs/vagrant/cli%2Fssh_config.html new file mode 100644 index 00000000..356a73ec --- /dev/null +++ b/devdocs/vagrant/cli%2Fssh_config.html @@ -0,0 +1,7 @@ +<h1 id="ssh-config"> SSH Config </h1> <p><strong>Command: <code>vagrant ssh-config [name|id]</code></strong></p> <p>This will output valid configuration for an SSH config file to SSH into the running Vagrant machine from <code>ssh</code> directly (instead of using <code>vagrant ssh</code>).</p> <h2 id="options"> Options </h2> <ul> <li> +<a href="#host-name"><code>--host NAME</code></a> - Name of the host for the outputted configuration. </li> </ul><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/cli/ssh_config.html" class="_attribution-link">https://www.vagrantup.com/docs/cli/ssh_config.html</a> + </p> +</div> diff --git a/devdocs/vagrant/cli%2Fstatus.html b/devdocs/vagrant/cli%2Fstatus.html new file mode 100644 index 00000000..5a7effd4 --- /dev/null +++ b/devdocs/vagrant/cli%2Fstatus.html @@ -0,0 +1,6 @@ +<h1 id="status"> Status </h1> <p><strong>Command: <code>vagrant status [name|id]</code></strong></p> <p>This will tell you the state of the machines Vagrant is managing.</p> <p>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.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/cli/status.html" class="_attribution-link">https://www.vagrantup.com/docs/cli/status.html</a> + </p> +</div> diff --git a/devdocs/vagrant/cli%2Fsuspend.html b/devdocs/vagrant/cli%2Fsuspend.html new file mode 100644 index 00000000..2bbb0642 --- /dev/null +++ b/devdocs/vagrant/cli%2Fsuspend.html @@ -0,0 +1,6 @@ +<h1 id="suspend"> Suspend </h1> <p><strong>Command: <code>vagrant suspend [name|id]</code></strong></p> <p>This suspends the guest machine Vagrant is managing, rather than fully <a href="halt">shutting it down</a> or <a href="destroy">destroying it</a>.</p> <p>A suspend effectively saves the <em>exact point-in-time state</em> of the machine, so that when you <a href="resume">resume</a> it later, it begins running immediately from that point, rather than doing a full boot.</p> <p>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.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/cli/suspend.html" class="_attribution-link">https://www.vagrantup.com/docs/cli/suspend.html</a> + </p> +</div> diff --git a/devdocs/vagrant/cli%2Fup.html b/devdocs/vagrant/cli%2Fup.html new file mode 100644 index 00000000..f85bcc49 --- /dev/null +++ b/devdocs/vagrant/cli%2Fup.html @@ -0,0 +1,14 @@ +<h1 id="up"> Up </h1> <p><strong>Command: <code>vagrant up [name|id]</code></strong></p> <p>This command creates and configures guest machines according to your <a href="../vagrantfile/index">Vagrantfile</a>.</p> <p>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.</p> <h2 id="options"> Options </h2> <ul> <li> +<p><a href="#name"><code>name</code></a> - Name of machine defined in <a href="../vagrantfile/index">Vagrantfile</a></p> </li> <li> +<p><a href="#id"><code>id</code></a> - Machine id found with <code>vagrant global-status</code>. Using <code>id</code> allows you to call <code>vagrant up id</code> from any directory.</p> </li> <li> +<p><a href="#no-destroy-on-error"><code>--[no-]destroy-on-error</code></a> - Destroy the newly created machine if a fatal, unexpected error occurs. This will only happen on the first <code>vagrant up</code>. By default this is set.</p> </li> <li> +<p><a href="#no-install-provider"><code>--[no-]install-provider</code></a> - If the requested provider is not installed, Vagrant will attempt to automatically install it if it can. By default this is enabled.</p> </li> <li> +<p><a href="#no-parallel"><code>--[no-]parallel</code></a> - Bring multiple machines up in parallel if the provider supports it. Please consult the provider documentation to see if this feature is supported.</p> </li> <li> +<p><a href="#provider-x"><code>--provider x</code></a> - Bring the machine up with the given <a href="../providers/index">provider</a>. By default this is "virtualbox".</p> </li> <li> +<p><a href="#no-provision"><code>--[no-]provision</code></a> - Force, or prevent, the provisioners to run.</p> </li> <li> +<p><a href="#provision-with-x-y-z"><code>--provision-with x,y,z</code></a> - This will only run the given provisioners. For example, if you have a <code>:shell</code> and <code>:chef_solo</code> provisioner and run <code>vagrant provision --provision-with shell</code>, only the shell provisioner will be run.</p> </li> </ul><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/cli/up.html" class="_attribution-link">https://www.vagrantup.com/docs/cli/up.html</a> + </p> +</div> diff --git a/devdocs/vagrant/cli%2Fvalidate.html b/devdocs/vagrant/cli%2Fvalidate.html new file mode 100644 index 00000000..0218ec84 --- /dev/null +++ b/devdocs/vagrant/cli%2Fvalidate.html @@ -0,0 +1,8 @@ +<h1 id="validate"> Validate </h1> <p><strong>Command: <code>vagrant validate</code></strong></p> <p>This command validates your <a href="../vagrantfile/index">Vagrantfile</a>.</p> <h2 id="examples"> Examples </h2> <div class="highlight"><pre class="highlight shell" data-language="shell">$ vagrant validate +Vagrantfile validated successfully. +</pre></div><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/cli/validate.html" class="_attribution-link">https://www.vagrantup.com/docs/cli/validate.html</a> + </p> +</div> diff --git a/devdocs/vagrant/cli%2Fversion.html b/devdocs/vagrant/cli%2Fversion.html new file mode 100644 index 00000000..fc8335b8 --- /dev/null +++ b/devdocs/vagrant/cli%2Fversion.html @@ -0,0 +1,6 @@ +<h1 id="version"> Version </h1> <p><strong>Command: <code>vagrant version</code></strong></p> <p>This command tells you the version of Vagrant you have installed as well as the latest version of Vagrant that is currently available.</p> <p>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 <code>vagrant --version</code>.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/cli/version.html" class="_attribution-link">https://www.vagrantup.com/docs/cli/version.html</a> + </p> +</div> diff --git a/devdocs/vagrant/docker%2Fbasics.html b/devdocs/vagrant/docker%2Fbasics.html new file mode 100644 index 00000000..595c111b --- /dev/null +++ b/devdocs/vagrant/docker%2Fbasics.html @@ -0,0 +1,28 @@ +<h1 id="docker-basic-usage"> Docker Basic Usage </h1> <p>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.</p> <p>The Docker provider <em>does not</em> require a <code>config.vm.box</code> 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.</p> <h2 id="docker-images"> Docker Images </h2> <p>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:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provider "docker" do |d| + d.image = "foo/bar" + end +end +</pre></div> +<p>When <code>vagrant up --provider=docker</code> is run, this will bring up the image <code>foo/bar</code>.</p> <p>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.</p> <h2 id="dockerfiles"> Dockerfiles </h2> <p>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:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provider "docker" do |d| + d.build_dir = "." + end +end +</pre></div> +<p>The above configuration will look for a <code>Dockerfile</code> in the same directory as the Vagrantfile. When <code>vagrant up --provider=docker</code> is run, Vagrant automatically builds that Dockerfile and starts a container based on that Dockerfile.</p> <p>The Dockerfile is rebuilt when <code>vagrant reload</code> is called.</p> <h2 id="synced-folders-and-networking"> Synced Folders and Networking </h2> <p>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.</p> <p>The Docker provider does not support specifying options for <code>owner</code> or <code>group</code> on folders synced with a docker container.</p> <p>Private and public networks are not currently supported.</p> <h3 id="volume-consistency"> Volume Consistency </h3> <p>Docker's <a href="https://docs.docker.com/v17.09/engine/admin/volumes/bind-mounts/">volume consistency</a> setting can be specified using the <code>docker_consistency</code> option when defining a synced folder. This can <a href="https://docs.docker.com/docker-for-mac/osxfs-caching">greatly improve performance on macOS</a>. An example is shown using the <code>cached</code> and <code>delegated</code> settings:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.synced_folder "/host/dir1", "/guest/dir1", docker_consistency: "cached" +config.vm.synced_folder "/host/dir2", "/guest/dir2", docker_consistency: "delegated" +</pre></div> +<h2 id="host-vm"> Host VM </h2> <p>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.</p> <p>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.</p> <p>By default, the host VM Vagrant spins up is <a href="https://github.com/hashicorp/vagrant/blob/master/plugins/providers/docker/hostmachine/Vagrantfile">backed by boot2docker</a>, because it launches quickly and uses little resources. But the host VM can be customized to point to <em>any</em> 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.</p> <blockquote class="alert alert-info"> <p><strong>Synced folder note:</strong> 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.</p> </blockquote> +<p>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:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provider "docker" do |d| + d.vagrant_vagrantfile = "../path/to/Vagrantfile" + end +end +</pre></div> +<p>The host VM will be spun up at the first <code>vagrant up</code> where the provider is Docker. To control this host VM, use the <a href="../cli/global-status">global-status command</a> along with global control.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/docker/basics.html" class="_attribution-link">https://www.vagrantup.com/docs/docker/basics.html</a> + </p> +</div> diff --git a/devdocs/vagrant/docker%2Fboxes.html b/devdocs/vagrant/docker%2Fboxes.html new file mode 100644 index 00000000..c8a89ea1 --- /dev/null +++ b/devdocs/vagrant/docker%2Fboxes.html @@ -0,0 +1,6 @@ +<h1 id="docker-boxes"> Docker Boxes </h1> <p>The Docker provider does not require a Vagrant box. The <code>config.vm.box</code> setting is completely optional.</p> <p>A box can still be used and specified, however, to provide defaults. Because the <code>Vagrantfile</code> within a box is loaded as part of the configuration loading sequence, it can be used to configure the foundation of a development environment.</p> <p>In general, however, you will not need a box with the Docker provider.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/docker/boxes.html" class="_attribution-link">https://www.vagrantup.com/docs/docker/boxes.html</a> + </p> +</div> diff --git a/devdocs/vagrant/docker%2Fcommands.html b/devdocs/vagrant/docker%2Fcommands.html new file mode 100644 index 00000000..08a5f415 --- /dev/null +++ b/devdocs/vagrant/docker%2Fcommands.html @@ -0,0 +1,41 @@ +<h1 id="docker-commands"> Docker Commands </h1> <p>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.</p> <h3 id="docker-exec"> docker-exec </h3> <p><code>vagrant docker-exec</code> 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.</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ vagrant docker-exec app -- rake db:migrate +</pre></div> +<p>The above would run <code>rake db:migrate</code> in the context of an <code>app</code> container.</p> <p>Note that the "name" corresponds to the name of the VM, <strong>not</strong> the name of the Docker container. Consider the following Vagrantfile:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure(2) do |config| + config.vm.provider "docker" do |d| + d.image = "consul" + end +end +</pre></div> +<p>This Vagrantfile will start the official Docker Consul image. However, the associated Vagrant command to <code>docker-exec</code> into this instance is:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ vagrant docker-exec -it -- /bin/sh +</pre></div> +<p>In particular, the command is actually:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ vagrant docker-exec default -it -- /bin/sh +</pre></div> +<p>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, <strong>not</strong> the name of the container:</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<p>The following command is invalid:</p> <div class="highlight"><pre class="highlight shell" data-language="shell"># Not valid +$ vagrant docker-exec -it nginx -- /bin/sh +</pre></div> +<p>This is because the "name" of the VM is "web", so the command is actually:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ vagrant docker-exec -it web -- /bin/sh +</pre></div> +<p>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:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ vagrant docker-exec -it consul -- /bin/sh +</pre></div> +<h3 id="docker-logs"> docker-logs </h3> <p><code>vagrant docker-logs</code> 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.</p> <h3 id="docker-run"> docker-run </h3> <p><code>vagrant docker-run</code> 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:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ vagrant docker-run app -- rake db:migrate +</pre></div> +<p>The above would run <code>rake db:migrate</code> in the context of an <code>app</code> container.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/docker/commands.html" class="_attribution-link">https://www.vagrantup.com/docs/docker/commands.html</a> + </p> +</div> diff --git a/devdocs/vagrant/docker%2Fconfiguration.html b/devdocs/vagrant/docker%2Fconfiguration.html new file mode 100644 index 00000000..87e132f9 --- /dev/null +++ b/devdocs/vagrant/docker%2Fconfiguration.html @@ -0,0 +1,33 @@ +<h1 id="docker-configuration"> Docker Configuration </h1> <p>The Docker provider has some provider-specific configuration options you may set. A complete reference is shown below.</p> <h3 id="required"> Required </h3> <p>One of the following settings is required when using the Docker provider:</p> <ul> <li> +<p><a href="#build_dir"><code>build_dir</code></a> (string) - The path to a directory containing a Dockerfile.</p> </li> <li> +<p><a href="#image"><code>image</code></a> (string) - The image to launch, specified by the image ID or a name such as <code>ubuntu:12.04</code>.</p> </li> <li> +<p><a href="#git_repo"><code>git_repo</code></a> (string) - The URL of a git repository to build the image from. Supports pulling specific tags, branches and revision, consult the <a href="https://docs.docker.com/engine/reference/commandline/build/#/git-repositories">docker documenation</a> for more information.</p> </li> </ul> <h3 id="optional"> Optional </h3> <p>General settings:</p> <ul> <li> +<p><a href="#build_args"><code>build_args</code></a> (array of strings) - Extra arguments to pass to <code>docker build</code> when <code>build_dir</code> is in use.</p> </li> <li> +<p><a href="#cmd"><code>cmd</code></a> (array of strings) - Custom command to run on the container. Example: <code>["ls", "/app"]</code>.</p> </li> <li> +<p><a href="#compose"><code>compose</code></a> (boolean) - If true, Vagrant will use <code>docker-compose</code> to manage the lifecycle and configuration of containers. This defaults to false.</p> </li> <li> +<p><a href="#compose_configuration"><code>compose_configuration</code></a> (Hash) - Configuration values used for populating the <code>docker-compose.yml</code> file. The value of this Hash is directly merged and written to the <code>docker-compose.yml</code> file allowing customization of non-services items like networks and volumes.</p> </li> <li> +<p><a href="#create_args"><code>create_args</code></a> (array of strings) - Additional arguments to pass to <code>docker run</code> when the container is started. This can be used to set parameters that are not exposed via the Vagrantfile.</p> </li> <li> +<p><a href="#dockerfile"><code>dockerfile</code></a> (string) - Name of the Dockerfile in the build directory. This defaults to "Dockerfile"</p> </li> <li> +<p><a href="#env"><code>env</code></a> (hash) - Environmental variables to expose into the container.</p> </li> <li> +<p><a href="#expose"><code>expose</code></a> (array of integers) - Ports to expose from the container but not to the host machine. Useful for links.</p> </li> <li> +<p><a href="#link"><code>link</code></a> (method, string argument) - Link this container to another by name. The argument should be in the format of <code>(name:alias)</code>. Example: <code>docker.link("db:db")</code>. Note, if you are linking to another container in the same Vagrantfile, make sure you call <code>vagrant up</code> with the <code>--no-parallel</code> flag.</p> </li> <li> +<p><a href="#force_host_vm"><code>force_host_vm</code></a> (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.</p> </li> <li> +<p><a href="#has_ssh"><code>has_ssh</code></a> (boolean) - If true, then Vagrant will support SSH with the container. This allows <code>vagrant ssh</code> to work, provisioners, etc. This defaults to false.</p> </li> <li> +<p><a href="#host_vm_build_dir_options"><code>host_vm_build_dir_options</code></a> (hash) - Synced folder options for the <code>build_dir</code>, since the build directory is synced using a synced folder if a host VM is in use.</p> </li> <li> +<p><a href="#name"><code>name</code></a> (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.</p> </li> <li> +<p><a href="#pull"><code>pull</code></a> (bool) - If true, the image will be pulled on every <code>up</code> and <code>reload</code>. Defaults to false.</p> </li> <li> +<p><a href="#ports"><code>ports</code></a> (array of strings) - Ports to expose from the container to the host. These should be in the format of <code>host:container</code>.</p> </li> <li> +<p><a href="#remains_running"><code>remains_running</code></a> (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.</p> </li> <li> +<p><a href="#stop_timeout"><code>stop_timeout</code></a> (integer) - The amount of time to wait when stopping a container before sending a SIGTERM to the process.</p> </li> <li> +<p><a href="#vagrant_machine"><code>vagrant_machine</code></a> (string) - The name of the Vagrant machine in the <code>vagrant_vagrantfile</code> to use as the host machine. This defaults to "default".</p> </li> <li> +<p><a href="#vagrant_vagrantfile"><code>vagrant_vagrantfile</code></a> (string) - Path to a Vagrantfile that contains the <code>vagrant_machine</code> to use as the host VM if needed.</p> </li> <li> +<p><a href="#volumes"><code>volumes</code></a> (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.</p> </li> </ul> <p>Below, we have settings related to auth. If these are set, then Vagrant will <code>docker login</code> prior to starting containers, allowing you to pull images from private repositories.</p> <ul> <li> +<p><a href="#email"><code>email</code></a> (string) - Email address for logging in.</p> </li> <li> +<p><a href="#username"><code>username</code></a> (string) - Username for logging in.</p> </li> <li> +<p><a href="#password"><code>password</code></a> (string) - Password for logging in.</p> </li> <li> +<p><a href="#auth_server"><code>auth_server</code></a> (string) - The server to use for authentication. If not set, the Docker Hub will be used.</p> </li> </ul><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/docker/configuration.html" class="_attribution-link">https://www.vagrantup.com/docs/docker/configuration.html</a> + </p> +</div> diff --git a/devdocs/vagrant/docker%2Findex.html b/devdocs/vagrant/docker%2Findex.html new file mode 100644 index 00000000..0744af89 --- /dev/null +++ b/devdocs/vagrant/docker%2Findex.html @@ -0,0 +1,7 @@ +<h1 id="docker"> Docker </h1> <p>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.</p> <blockquote class="alert alert-warning"> <p><strong>Warning: Docker knowledge assumed.</strong> 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 <a href="../virtualbox/index">VirtualBox</a>.</p> </blockquote> +<p>Use the navigation to the left to find a specific Docker topic to read more about.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/docker/" class="_attribution-link">https://www.vagrantup.com/docs/docker/</a> + </p> +</div> diff --git a/devdocs/vagrant/hyperv%2Fboxes.html b/devdocs/vagrant/hyperv%2Fboxes.html new file mode 100644 index 00000000..ade9dc48 --- /dev/null +++ b/devdocs/vagrant/hyperv%2Fboxes.html @@ -0,0 +1,19 @@ +<h1 id="creating-a-base-box"> Creating a Base Box </h1> <p>As with <a href="../providers/basic_usage">every Vagrant provider</a>, the Vagrant Hyper-V provider has a custom box format that affects how base boxes are made.</p> <p>Prior to reading this, you should read the <a href="../boxes/base">general guide to creating base boxes</a>. 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.</p> <p>Additionally, it is helpful to understand the <a href="../boxes/format">basics of the box file format</a>.</p> <blockquote class="alert alert-warning"> <p><strong>Advanced topic!</strong> 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.</p> </blockquote> +<h2 id="additional-software"> Additional Software </h2> <p>In addition to the software that should be installed based on the <a href="../boxes/base">general guide to creating base boxes</a>, Hyper-V base boxes require some additional software.</p> <h3 id="hyper-v-kernel-modules"> Hyper-V Kernel Modules </h3> <p>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.</p> <p>You can verify Hyper-V kernel modules are properly installed by running <code>lsmod</code> on Linux machines and looking for modules prefixed with <code>hv_</code>. 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.</p> <p>For most newer Linux distributions, the Hyper-V modules will be available out of the box.</p> <p>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:</p> <div class="highlight"><pre class="highlight plaintext">$ 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/ +</pre></div> +<h2 id="packaging-the-box"> Packaging the Box </h2> <p>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:</p> <div class="highlight"><pre class="highlight plaintext">. +|-- Snapshots +|-- Virtual Hard drives +|-- Virtual Machines +</pre></div> +<p>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.</p> <p>Then, create the "metadata.json" file necessary for the box, as documented in <a href="../boxes/format">basics of the box file format</a>. The proper provider value to use for the metadata is "hyperv".</p> <p>Finally, create an archive of those contents (but <em>not</em> the parent folder) using a tool such as <code>tar</code>:</p> <div class="highlight"><pre class="highlight plaintext">$ tar cvzf ~/custom.box ./* +</pre></div> +<p>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.</p> <h2 id="additional-help"> Additional Help </h2> <p>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:</p> <ul> <li> +<a href="https://github.com/hashicorp/vagrant/issues/5419#issuecomment-86235427">Ubuntu 14.04.2 without secure boot</a> </li> </ul><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/hyperv/boxes.html" class="_attribution-link">https://www.vagrantup.com/docs/hyperv/boxes.html</a> + </p> +</div> diff --git a/devdocs/vagrant/hyperv%2Fconfiguration.html b/devdocs/vagrant/hyperv%2Fconfiguration.html new file mode 100644 index 00000000..af18e540 --- /dev/null +++ b/devdocs/vagrant/hyperv%2Fconfiguration.html @@ -0,0 +1,34 @@ +<h1 id="configuration"> Configuration </h1> <p>The Vagrant Hyper-V provider has some provider-specific configuration options you may set. A complete reference is shown below:</p> <ul> <li> +<a href="#auto_start_action"><code>auto_start_action</code></a> (Nothing, StartIfRunning, Start) - Automatic start action for VM on host startup. Default: Nothing. </li> <li> +<a href="#auto_stop_action"><code>auto_stop_action</code></a> (ShutDown, TurnOff, Save) - Automatic stop action for VM on host shutdown. Default: ShutDown. </li> <li> +<a href="#cpus"><code>cpus</code></a> (integer) - Number of virtual CPUs allocated to VM at startup. </li> <li> +<a href="#differencing_disk"><code>differencing_disk</code></a> (boolean) - <strong>Deprecated</strong> Use differencing disk instead of cloning entire VHD (use <code>linked_clone</code> instead) Default: false. </li> <li> +<a href="#enable_virtualization_extensions"><code>enable_virtualization_extensions</code></a> (boolean) - Enable virtualization extensions for the virtual CPUs. Default: false </li> <li> +<a href="#enable_checkpoints"><code>enable_checkpoints</code></a> (boolean) Enable checkpoints of the VM. Default: false </li> <li> +<a href="#enable_automatic_checkpoints"><code>enable_automatic_checkpoints</code></a> (boolean) Enable automatic checkpoints of the VM. Default: false </li> <li> +<a href="#ip_address_timeout"><code>ip_address_timeout</code></a> (integer) - Number of seconds to wait for the VM to report an IP address. Default: 120. </li> <li> +<a href="#linked_clone"><code>linked_clone</code></a> (boolean) - Use differencing disk instead of cloning entire VHD. Default: false </li> <li> +<a href="#mac"><code>mac</code></a> (string) - MAC address for the guest network interface </li> <li> +<a href="#maxmemory"><code>maxmemory</code></a> (integer) - Maximum number of megabytes allowed to be allocated for the VM. When set Dynamic Memory Allocation will be enabled. </li> <li> +<a href="#memory"><code>memory</code></a> (integer) - Number of megabytes allocated to VM at startup. If <code>maxmemory</code> is set, this will be amount of memory allocated at startup. </li> <li> +<a href="#vlan_id"><code>vlan_id</code></a> (integer) - VLAN ID for the guest network interface. </li> <li> +<a href="#vmname"><code>vmname</code></a> (string) - Name of virtual machine as shown in Hyper-V manager. Default: Generated name. </li> <li> +<a href="#vm_integration_services"><code>vm_integration_services</code></a> (Hash) - Hash to set the state of integration services. (Note: Unknown key values will be passed directly.) <ul> <li> +<a href="#guest_service_interface"><code>guest_service_interface</code></a> (boolean) </li> <li> +<a href="#heartbeat"><code>heartbeat</code></a> (boolean) </li> <li> +<a href="#key_value_pair_exchange"><code>key_value_pair_exchange</code></a> (boolean) </li> <li> +<a href="#shutdown"><code>shutdown</code></a> (boolean) </li> <li> +<a href="#time_synchronization"><code>time_synchronization</code></a> (boolean) </li> <li> +<a href="#vss"><code>vss</code></a> (boolean) </li> </ul> </li> </ul> <h2 id="vm-integration-services"> VM Integration Services </h2> <p>The <code>vm_integration_services</code> 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.</p> <p>For example, if a new <code>CustomVMSRV</code> VM integration service was added and Vagrant is not aware of this new service name, it can be provided as the key value explicitly:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.provider "hyperv" do |h| + h.vm_integration_services = { + guest_service_interface: true, + CustomVMSRV: true + } +end +</pre></div> +<p>This example would enable the <code>GuestServiceInterface</code> (which Vagrant is aware) and <code>CustomVMSRV</code> (which Vagrant is <em>not</em> aware) VM integration services.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/hyperv/configuration.html" class="_attribution-link">https://www.vagrantup.com/docs/hyperv/configuration.html</a> + </p> +</div> diff --git a/devdocs/vagrant/hyperv%2Findex.html b/devdocs/vagrant/hyperv%2Findex.html new file mode 100644 index 00000000..803b685f --- /dev/null +++ b/devdocs/vagrant/hyperv%2Findex.html @@ -0,0 +1,6 @@ +<h1 id="hyper-v"> Hyper-V </h1> <p>Vagrant comes with support out of the box for <a href="https://en.wikipedia.org/wiki/Hyper-V">Hyper-V</a>, a native hypervisor written by Microsoft. Hyper-V is available by default for almost all Windows 8.1 and later installs.</p> <p>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.</p> <p>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:</p> <p><code>Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All</code></p> <p>See official documentation <a href="https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v">here</a>.</p> <blockquote class="alert alert-warning"> <p><strong>Warning:</strong> Enabling Hyper-V will cause VirtualBox, VMware, and any other virtualization technology to no longer work. See <a href="http://www.hanselman.com/blog/SwitchEasilyBetweenVirtualBoxAndHyperVWithABCDEditBootEntryInWindows81.aspx">this blog post</a> 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.</p> </blockquote><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/hyperv/" class="_attribution-link">https://www.vagrantup.com/docs/hyperv/</a> + </p> +</div> diff --git a/devdocs/vagrant/hyperv%2Flimitations.html b/devdocs/vagrant/hyperv%2Flimitations.html new file mode 100644 index 00000000..c001f596 --- /dev/null +++ b/devdocs/vagrant/hyperv%2Flimitations.html @@ -0,0 +1,6 @@ +<h1 id="limitations"> Limitations </h1> <p>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.</p> <h2 id="limited-networking"> Limited Networking </h2> <p>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.</p> <p>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.</p> <p>However, the IP address of the machine will be reported as part of the <code>vagrant up</code>, and you can use that IP address as if it were a host only network.</p> <h2 id="snapshots"> Snapshots </h2> <p>Restoring snapshot VMs using <code>vagrant snapshot pop</code> or <code>vagrant snapshot restore</code> will sometimes raise errors when mounting SMB shared folders, however these mounts will still work inside the guest.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/hyperv/limitations.html" class="_attribution-link">https://www.vagrantup.com/docs/hyperv/limitations.html</a> + </p> +</div> diff --git a/devdocs/vagrant/hyperv%2Fusage.html b/devdocs/vagrant/hyperv%2Fusage.html new file mode 100644 index 00000000..aaea813f --- /dev/null +++ b/devdocs/vagrant/hyperv%2Fusage.html @@ -0,0 +1,6 @@ +<h1 id="usage"> Usage </h1> <p>The Vagrant Hyper-V provider is used just like any other provider. Please read the general <a href="../providers/basic_usage">basic usage</a> page for providers.</p> <p>The value to use for the <code>--provider</code> flag is <code>hyperv</code>.</p> <p>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.</p> <p>Boxes for Hyper-V can be easily found on <a href="https://vagrantcloud.com/boxes/search">HashiCorp's Vagrant Cloud</a>. To get started, you might want to try the <code>hashicorp/precise64</code> box.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/hyperv/usage.html" class="_attribution-link">https://www.vagrantup.com/docs/hyperv/usage.html</a> + </p> +</div> diff --git a/devdocs/vagrant/index b/devdocs/vagrant/index new file mode 100644 index 00000000..529a25c3 --- /dev/null +++ b/devdocs/vagrant/index @@ -0,0 +1 @@ +((pages . ["index" "installation/index" "cli/box" "cli/plugin" "cli/powershell" "installation/upgrading-from-1-0" "installation/uninstallation" "cli/index" "cli/cloud" "cli/connect" "cli/destroy" "cli/global-status" "cli/halt" "cli/init" "cli/package" "cli/port" "cli/provision" "installation/source" "installation/backwards-compatibility" "installation/upgrading" "cli/login" "cli/rdp" "cli/reload" "cli/resume" "cli/share" "cli/ssh_config" "cli/status" "cli/suspend" "cli/validate" "cli/version" "cli/up" "cli/non-primary" "cli/aliases" "share/index" "cli/ssh" "cli/machine-readable" "cli/snapshot" "share/http" "share/connect" "share/security" "share/provider" "vagrantfile/machine_settings" "vagrantfile/ssh_settings" "share/ssh" "vagrantfile/version" "vagrantfile/vagrant_version" "boxes/versioning" "vagrantfile/index" "vagrantfile/tips" "vagrantfile/winrm_settings" "vagrantfile/winssh_settings" "boxes/base" "vagrantfile/vagrant_settings" "boxes" "boxes/format" "boxes/info" "provisioning/file" "provisioning/shell" "provisioning/ansible" "provisioning/cfengine" "provisioning/index" "provisioning/basic_usage" "provisioning/ansible_local" "provisioning/chef_solo" "provisioning/chef_client" "provisioning/puppet_agent" "provisioning/salt" "provisioning/chef_zero" "provisioning/chef_apply" "provisioning/docker" "provisioning/puppet_apply" "networking/index" "networking/forwarded_ports" "networking/basic_usage" "networking/private_network" "networking/public_network" "synced-folders/index" "synced-folders/basic_usage" "synced-folders/nfs" "synced-folders/rsync" "synced-folders/smb" "multi-machine/index" "providers/installation" "synced-folders/virtualbox" "providers/index" "providers/basic_usage" "providers/configuration" "virtualbox/usage" "virtualbox/boxes" "virtualbox/configuration" "providers/default" "virtualbox/index" "virtualbox/networking" "virtualbox/common-issues" "vmware/index" "vmware/installation" "vmware/boxes" "vmware/configuration" "vmware/usage" "vmware/vagrant-vmware-utility" "vmware/known-issues" "vmware/kernel-upgrade" "docker/index" "docker/basics" "docker/commands" "docker/boxes" "docker/configuration" "hyperv/usage" "hyperv/boxes" "hyperv/index" "hyperv/limitations" "hyperv/configuration" "providers/custom" "plugins/index" "plugins/development-basics" "plugins/commands" "plugins/usage" "plugins/configuration" "plugins/action-hooks" "plugins/host-capabilities" "plugins/providers" "plugins/guests" "plugins/guest-capabilities" "plugins/hosts" "plugins/provisioners" "push/index" "push/ftp" "plugins/packaging" "push/heroku" "push/local-exec" "triggers/index" "triggers/configuration" "triggers/usage" "other/index" "other/debugging" "other/environmental-variables" "other/wsl" "cli/rsync" "vmware" "cli/rsync-auto" "provisioning/ansible_intro" "provisioning/chef_common" "provisioning/ansible_common" "multi-machine" "provisioning"]) (entries . [((name . "Action Hooks") (path . "plugins/action-hooks") (type . "Plugins")) ((name . "Additional Box Information") (path . "boxes/info") (type . "Boxes")) ((name . "Aliases") (path . "cli/aliases") (type . "Commands (CLI)")) ((name . "Ansible and Vagrant") (path . "provisioning/ansible_intro") (type . "Provisioning")) ((name . "Ansible Local Provisioner") (path . "provisioning/ansible_local") (type . "Provisioning")) ((name . "Ansible Provisioner") (path . "provisioning/ansible") (type . "Provisioning")) ((name . "Backwards Compatibility") (path . "installation/backwards-compatibility") (type . "Installation")) ((name . "Basic Provider Usage") (path . "providers/basic_usage") (type . "Providers")) ((name . "Basic Usage") (path . "synced-folders/basic_usage") (type . "Synced Folders")) ((name . "Basic Usage") (path . "triggers/usage") (type . "Triggers")) ((name . "Basic Usage of Networking") (path . "networking/basic_usage") (type . "Networking")) ((name . "Basic Usage of Provisioners") (path . "provisioning/basic_usage") (type . "Provisioning")) ((name . "Box File Format") (path . "boxes/format") (type . "Boxes")) ((name . "Box Versioning") (path . "boxes/versioning") (type . "Boxes")) ((name . "Boxes") (path . "boxes") (type . "Boxes")) ((name . "Boxes") (path . "vmware/boxes") (type . "Providers: VMware")) ((name . "CFEngine Provisioner") (path . "provisioning/cfengine") (type . "Provisioning")) ((name . "Chef Apply Provisioner") (path . "provisioning/chef_apply") (type . "Provisioning")) ((name . "Chef Client Provisioner") (path . "provisioning/chef_client") (type . "Provisioning")) ((name . "Chef Solo Provisioner") (path . "provisioning/chef_solo") (type . "Provisioning")) ((name . "Chef Zero Provisioner") (path . "provisioning/chef_zero") (type . "Provisioning")) ((name . "Command-Line Interface") (path . "cli/index") (type . "Commands (CLI)")) ((name . "Common Issues") (path . "virtualbox/common-issues") (type . "Providers: VirtualBox")) ((name . "config.ssh.username") (path . "vagrantfile/ssh_settings#config-ssh-username") (type . "Config")) ((name . "config.vagrant.host") (path . "vagrantfile/vagrant_settings#config-vagrant-host") (type . "Config")) ((name . "config.vm.base_mac") (path . "vagrantfile/machine_settings#config-vm-base_mac") (type . "Config")) ((name . "config.winrm.username") (path . "vagrantfile/winrm_settings#config-winrm-username") (type . "Config")) ((name . "Configuration") (path . "vmware/configuration") (type . "Providers: VMware")) ((name . "Configuration") (path . "virtualbox/configuration") (type . "Providers: VirtualBox")) ((name . "Configuration") (path . "providers/configuration") (type . "Providers")) ((name . "Configuration") (path . "hyperv/configuration") (type . "Providers: Hyper-V")) ((name . "Configuration") (path . "triggers/configuration") (type . "Triggers")) ((name . "Configuration Version") (path . "vagrantfile/version") (type . "Vagrantfile")) ((name . "Creating a Base Box") (path . "boxes/base") (type . "Boxes")) ((name . "Creating a Base Box") (path . "hyperv/boxes") (type . "Providers: Hyper-V")) ((name . "Creating a Base Box") (path . "virtualbox/boxes") (type . "Providers: VirtualBox")) ((name . "Custom Provider") (path . "share/provider") (type . "Vagrant Share")) ((name . "Custom Provider") (path . "providers/custom") (type . "Providers")) ((name . "Debugging") (path . "other/debugging") (type . "Other")) ((name . "Default Provider") (path . "providers/default") (type . "Providers")) ((name . "Docker") (path . "docker/index") (type . "Providers: Docker")) ((name . "Docker Basic Usage") (path . "docker/basics") (type . "Providers: Docker")) ((name . "Docker Boxes") (path . "docker/boxes") (type . "Providers: Docker")) ((name . "Docker Commands") (path . "docker/commands") (type . "Providers: Docker")) ((name . "Docker Configuration") (path . "docker/configuration") (type . "Providers: Docker")) ((name . "Docker Provisioner") (path . "provisioning/docker") (type . "Provisioning")) ((name . "Environmental Variables") (path . "other/environmental-variables") (type . "Other")) ((name . "File Provisioner") (path . "provisioning/file") (type . "Provisioning")) ((name . "Forwarded Ports") (path . "networking/forwarded_ports") (type . "Networking")) ((name . "FTP & SFTP Strategy") (path . "push/ftp") (type . "Push")) ((name . "Heroku Strategy") (path . "push/heroku") (type . "Push")) ((name . "HTTP Sharing") (path . "share/http") (type . "Vagrant Share")) ((name . "Hyper-V") (path . "hyperv/index") (type . "Providers: Hyper-V")) ((name . "Installation") (path . "vmware/installation") (type . "Providers: VMware")) ((name . "Installing Vagrant") (path . "installation/index") (type . "Installation")) ((name . "Installing Vagrant from Source") (path . "installation/source") (type . "Installation")) ((name . "Kernel Upgrade") (path . "vmware/kernel-upgrade") (type . "Providers: VMware")) ((name . "Known Issues") (path . "vmware/known-issues") (type . "Providers: VMware")) ((name . "Limitations") (path . "hyperv/limitations") (type . "Providers: Hyper-V")) ((name . "Local Exec Strategy") (path . "push/local-exec") (type . "Push")) ((name . "Machine Readable Output") (path . "cli/machine-readable") (type . "Commands (CLI)")) ((name . "Machine Settings") (path . "vagrantfile/machine_settings") (type . "Vagrantfile")) ((name . "Minimum Vagrant Version") (path . "vagrantfile/vagrant_version") (type . "Vagrantfile")) ((name . "More Commands") (path . "cli/non-primary") (type . "Commands (CLI)")) ((name . "Multi-Machine") (path . "multi-machine") (type . "Multi-Machine")) ((name . "Multi-Machine") (path . "multi-machine/index") (type . "Multi-Machine")) ((name . "Networking") (path . "virtualbox/networking") (type . "Providers: VirtualBox")) ((name . "Networking") (path . "networking/index") (type . "Networking")) ((name . "NFS") (path . "synced-folders/nfs") (type . "Synced Folders")) ((name . "Other") (path . "other/index") (type . "Other")) ((name . "Plugin Development Basics") (path . "plugins/development-basics") (type . "Plugins")) ((name . "Plugin Development: Commands") (path . "plugins/commands") (type . "Plugins")) ((name . "Plugin Development: Configuration") (path . "plugins/configuration") (type . "Plugins")) ((name . "Plugin Development: Guest Capabilities") (path . "plugins/guest-capabilities") (type . "Plugins")) ((name . "Plugin Development: Guests") (path . "plugins/guests") (type . "Plugins")) ((name . "Plugin Development: Host Capabilities") (path . "plugins/host-capabilities") (type . "Plugins")) ((name . "Plugin Development: Hosts") (path . "plugins/hosts") (type . "Plugins")) ((name . "Plugin Development: Packaging & Distribution") (path . "plugins/packaging") (type . "Plugins")) ((name . "Plugin Development: Providers") (path . "plugins/providers") (type . "Plugins")) ((name . "Plugin Development: Provisioners") (path . "plugins/provisioners") (type . "Plugins")) ((name . "Plugin Usage") (path . "plugins/usage") (type . "Plugins")) ((name . "Plugins") (path . "plugins/index") (type . "Plugins")) ((name . "Private Networks") (path . "networking/private_network") (type . "Networking")) ((name . "Provider Installation") (path . "providers/installation") (type . "Providers")) ((name . "Providers") (path . "providers/index") (type . "Providers")) ((name . "Provisioning") (path . "provisioning") (type . "Provisioning")) ((name . "Provisioning") (path . "provisioning/index") (type . "Provisioning")) ((name . "Public Networks") (path . "networking/public_network") (type . "Networking")) ((name . "Puppet Agent Provisioner") (path . "provisioning/puppet_agent") (type . "Provisioning")) ((name . "Puppet Apply Provisioner") (path . "provisioning/puppet_apply") (type . "Provisioning")) ((name . "RSync") (path . "synced-folders/rsync") (type . "Synced Folders")) ((name . "Salt Provisioner") (path . "provisioning/salt") (type . "Provisioning")) ((name . "Security") (path . "share/security") (type . "Vagrant Share")) ((name . "Shared Ansible Options") (path . "provisioning/ansible_common") (type . "Provisioning")) ((name . "Shared Chef Options") (path . "provisioning/chef_common") (type . "Provisioning")) ((name . "Shell Provisioner") (path . "provisioning/shell") (type . "Provisioning")) ((name . "SMB") (path . "synced-folders/smb") (type . "Synced Folders")) ((name . "SSH Settings") (path . "vagrantfile/ssh_settings") (type . "Vagrantfile")) ((name . "SSH Sharing") (path . "share/ssh") (type . "Vagrant Share")) ((name . "Synced Folders") (path . "synced-folders/index") (type . "Synced Folders")) ((name . "Tips & Tricks") (path . "vagrantfile/tips") (type . "Vagrantfile")) ((name . "Uninstalling Vagrant") (path . "installation/uninstallation") (type . "Installation")) ((name . "Upgrading From Vagrant 1.0.x") (path . "installation/upgrading-from-1-0") (type . "Installation")) ((name . "Upgrading Vagrant") (path . "installation/upgrading") (type . "Installation")) ((name . "Usage") (path . "virtualbox/usage") (type . "Providers: VirtualBox")) ((name . "Usage") (path . "vmware/usage") (type . "Providers: VMware")) ((name . "Usage") (path . "hyperv/usage") (type . "Providers: Hyper-V")) ((name . "Vagrant and Windows Subsystem for Linux") (path . "other/wsl") (type . "Other")) ((name . "vagrant box") (path . "cli/box") (type . "Commands (CLI)")) ((name . "vagrant cloud") (path . "cli/cloud") (type . "Commands (CLI)")) ((name . "vagrant connect") (path . "cli/connect") (type . "Commands (CLI)")) ((name . "Vagrant Connect") (path . "share/connect") (type . "Vagrant Share")) ((name . "vagrant destroy") (path . "cli/destroy") (type . "Commands (CLI)")) ((name . "vagrant global-status") (path . "cli/global-status") (type . "Commands (CLI)")) ((name . "vagrant halt") (path . "cli/halt") (type . "Commands (CLI)")) ((name . "vagrant init") (path . "cli/init") (type . "Commands (CLI)")) ((name . "vagrant login") (path . "cli/login") (type . "Commands (CLI)")) ((name . "vagrant package") (path . "cli/package") (type . "Commands (CLI)")) ((name . "vagrant plugin") (path . "cli/plugin") (type . "Commands (CLI)")) ((name . "vagrant port") (path . "cli/port") (type . "Commands (CLI)")) ((name . "vagrant powershell") (path . "cli/powershell") (type . "Commands (CLI)")) ((name . "vagrant provision") (path . "cli/provision") (type . "Commands (CLI)")) ((name . "Vagrant Push") (path . "push/index") (type . "Push")) ((name . "vagrant rdp") (path . "cli/rdp") (type . "Commands (CLI)")) ((name . "vagrant reload") (path . "cli/reload") (type . "Commands (CLI)")) ((name . "vagrant resume") (path . "cli/resume") (type . "Commands (CLI)")) ((name . "vagrant rsync") (path . "cli/rsync") (type . "Commands (CLI)")) ((name . "vagrant rsync-auto") (path . "cli/rsync-auto") (type . "Commands (CLI)")) ((name . "Vagrant Settings") (path . "vagrantfile/vagrant_settings") (type . "Vagrantfile")) ((name . "Vagrant Share") (path . "share/index") (type . "Vagrant Share")) ((name . "vagrant share") (path . "cli/share") (type . "Commands (CLI)")) ((name . "vagrant snapshot") (path . "cli/snapshot") (type . "Commands (CLI)")) ((name . "vagrant ssh") (path . "cli/ssh") (type . "Commands (CLI)")) ((name . "vagrant ssh-config") (path . "cli/ssh_config") (type . "Commands (CLI)")) ((name . "vagrant status") (path . "cli/status") (type . "Commands (CLI)")) ((name . "vagrant suspend") (path . "cli/suspend") (type . "Commands (CLI)")) ((name . "Vagrant Triggers") (path . "triggers/index") (type . "Triggers")) ((name . "vagrant up") (path . "cli/up") (type . "Commands (CLI)")) ((name . "vagrant validate") (path . "cli/validate") (type . "Commands (CLI)")) ((name . "vagrant version") (path . "cli/version") (type . "Commands (CLI)")) ((name . "Vagrant VMware Utility Installation") (path . "vmware/vagrant-vmware-utility") (type . "Providers: VMware")) ((name . "Vagrantfile") (path . "vagrantfile/index") (type . "Vagrantfile")) ((name . "VirtualBox") (path . "virtualbox/index") (type . "Providers: VirtualBox")) ((name . "VirtualBox") (path . "synced-folders/virtualbox") (type . "Synced Folders")) ((name . "VMware") (path . "vmware/index") (type . "Providers: VMware")) ((name . "VMware") (path . "vmware") (type . "Providers: VMware")) ((name . "WinRM Settings") (path . "vagrantfile/winrm_settings") (type . "Vagrantfile")) ((name . "WinSSH") (path . "vagrantfile/winssh_settings") (type . "Vagrantfile"))]) (types . [((name . "Boxes") (count . 5) (slug . "boxes")) ((name . "Commands (CLI)") (count . 31) (slug . "commands-cli")) ((name . "Config") (count . 4) (slug . "config")) ((name . "Installation") (count . 6) (slug . "installation")) ((name . "Multi-Machine") (count . 2) (slug . "multi-machine")) ((name . "Networking") (count . 5) (slug . "networking")) ((name . "Other") (count . 4) (slug . "other")) ((name . "Plugins") (count . 13) (slug . "plugins")) ((name . "Providers") (count . 6) (slug . "providers")) ((name . "Providers: Docker") (count . 5) (slug . "providers-docker")) ((name . "Providers: Hyper-V") (count . 5) (slug . "providers-hyper-v")) ((name . "Providers: VirtualBox") (count . 6) (slug . "providers-virtualbox")) ((name . "Providers: VMware") (count . 9) (slug . "providers-vmware")) ((name . "Provisioning") (count . 19) (slug . "provisioning")) ((name . "Push") (count . 4) (slug . "push")) ((name . "Synced Folders") (count . 6) (slug . "synced-folders")) ((name . "Triggers") (count . 3) (slug . "triggers")) ((name . "Vagrant Share") (count . 6) (slug . "vagrant-share")) ((name . "Vagrantfile") (count . 9) (slug . "vagrantfile"))]))
\ No newline at end of file diff --git a/devdocs/vagrant/index.html b/devdocs/vagrant/index.html new file mode 100644 index 00000000..c2b9b742 --- /dev/null +++ b/devdocs/vagrant/index.html @@ -0,0 +1,6 @@ +<h1 id="vagrant-documentation"> Vagrant Documentation </h1> <p>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 <a href="https://www.vagrantup.com/intro/getting-started/index.html">getting started guide</a> first, and then return to this page.</p> <p>The navigation will take you through each component of Vagrant. Click on a navigation item to get started, or read more about <a href="https://www.vagrantup.com/intro/index.html">why developers, designers, and operators choose Vagrant</a> for their needs.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/index.html" class="_attribution-link">https://www.vagrantup.com/docs/index.html</a> + </p> +</div> diff --git a/devdocs/vagrant/installation%2Fbackwards-compatibility.html b/devdocs/vagrant/installation%2Fbackwards-compatibility.html new file mode 100644 index 00000000..a96f5a84 --- /dev/null +++ b/devdocs/vagrant/installation%2Fbackwards-compatibility.html @@ -0,0 +1,6 @@ +<h1 id="backwards-compatibility"> Backwards Compatibility </h1> <h2 id="for-1-0-x"> For 1.0.x </h2> <p>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.</p> <p>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.</p> <p>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.</p> <h2 id="for-1-x"> For 1.x </h2> <p>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.</p> <p>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.</p> <p>Vagrant 2.0 final will have a stable Vagrantfile format that will remain backwards compatible, just as 1.0 is considered stable.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/installation/backwards-compatibility.html" class="_attribution-link">https://www.vagrantup.com/docs/installation/backwards-compatibility.html</a> + </p> +</div> diff --git a/devdocs/vagrant/installation%2Findex.html b/devdocs/vagrant/installation%2Findex.html new file mode 100644 index 00000000..ee69a0d3 --- /dev/null +++ b/devdocs/vagrant/installation%2Findex.html @@ -0,0 +1,26 @@ +<h1 id="installing-vagrant"> Installing Vagrant </h1> <p>Installing Vagrant is extremely easy. Head over to the <a href="https://www.vagrantup.com/downloads.html">Vagrant downloads page</a> and get the appropriate installer or package for your platform. Install the package using standard procedures for your operating system.</p> <p>The installer will automatically add <code>vagrant</code> 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).</p> <blockquote class="alert alert-warning" role="alert"> <p><strong>Looking for the gem install?</strong> Vagrant 1.0.x had the option to be installed as a <a href="https://en.wikipedia.org/wiki/RubyGems">RubyGem</a>. This installation method is no longer supported. If you have an old version of Vagrant installed via Rubygems, please remove it prior to installing newer versions of Vagrant.</p> </blockquote> +<blockquote class="alert alert-warning" role="alert"> <p><strong>Beware of system package managers!</strong> Some operating system distributions include a vagrant package in their upstream package repos. Please do not install Vagrant in this manner. Typically these packages are missing dependencies or include very outdated versions of Vagrant. If you install via your system's package manager, it is very likely that you will experience issues. Please use the official installers on the downloads page.</p> </blockquote> +<h2 id="running-multiple-hypervisors"> Running Multiple Hypervisors </h2> <p>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:</p> <div class="highlight"><pre class="highlight plaintext">There was an error while executing `VBoxManage`, a CLI used by Vagrant for controlling VirtualBox. The command and stderr is shown below. + +Command: ["startvm", <ID of the VM>, "--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 +</pre></div> +<p>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.</p> <h3 id="linux-virtualbox-and-kvm"> Linux, VirtualBox, and KVM </h3> <p>The above error message is because another hypervisor (like KVM) is in use. We must blacklist these in order for VirtualBox to run correctly.</p> <p>First find out the name of the hypervisor:</p> <div class="highlight"><pre class="highlight plaintext">$ lsmod | grep kvm +kvm_intel 204800 6 +kvm 593920 1 kvm_intel +irqbypass 16384 1 kvm +</pre></div> +<p>The one we're interested in is <code>kvm_intel</code>. You might have another.</p> <p>Blacklist the hypervisor (run the following as root):</p> <div class="highlight"><pre class="highlight plaintext"># echo 'blacklist kvm-intel' >> /etc/modprobe.d/blacklist.conf +</pre></div> +<p>Restart your machine and try running vagrant again.</p> <h3 id="windows-virtualbox-and-hyper-v"> Windows, VirtualBox, and Hyper-V </h3> <p>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:</p> <div class="highlight"><pre class="highlight powershell" data-language="shell">Disable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V-All +</pre></div> +<p>You can also disable it by going through the Windows system settings:</p> <ul> <li>Right click on the Windows button and select ‘Apps and Features’. </li> <li>Select Turn Windows Features on or off. </li> <li>Unselect Hyper-V and click OK. </li> </ul> <p>You might have to reboot your machine for the changes to take effect. More information about Hyper-V can be read <a href="https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v">here</a>.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/installation/" class="_attribution-link">https://www.vagrantup.com/docs/installation/</a> + </p> +</div> diff --git a/devdocs/vagrant/installation%2Fsource.html b/devdocs/vagrant/installation%2Fsource.html new file mode 100644 index 00000000..3d95033a --- /dev/null +++ b/devdocs/vagrant/installation%2Fsource.html @@ -0,0 +1,18 @@ +<h1 id="installing-vagrant-from-source"> Installing Vagrant from Source </h1> <p>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.</p> <h2 id="install-ruby"> Install Ruby </h2> <p>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 <code>gemspec</code>. Please refer to the <code>vagrant.gemspec</code> 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:</p> <ul> <li>Do <strong>NOT</strong> use the system Ruby - use a Ruby version manager like rvm or chruby </li> <li>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. </li> </ul> <h2 id="clone-vagrant"> Clone Vagrant </h2> <p>Clone Vagrant's repository from GitHub into the directory where you keep code on your machine:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ git clone https://github.com/hashicorp/vagrant.git +</pre></div> +<p>Next, <code>cd</code> into that path. All commands will be run from this path:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ cd /path/to/your/vagrant/clone +</pre></div> +<p>Run the <code>bundle</code> command with a required version* to install the requirements:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ bundle install +</pre></div> +<p>You can now run Vagrant by running <code>bundle exec vagrant</code> from inside that directory.</p> <h2 id="use-locally"> Use Locally </h2> <p>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.</p> <p>First, run the following command from the Vagrant repo:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ bundle --binstubs exec +</pre></div> +<p>This will generate files in <code>exec/</code>, including <code>vagrant</code>. You can now specify the full path to the <code>exec/vagrant</code> anywhere on your operating system:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ /path/to/vagrant/exec/vagrant init -m hashicorp/precise64 +</pre></div> +<p>Note that you <em>will</em> receive warnings that running Vagrant like this is not supported. It's true. It's not. You should listen to those warnings.</p> <p>If you do not want to specify the full path to Vagrant (i.e. you just want to run <code>vagrant</code>), you can create a symbolic link to your exec:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ ln -sf /path/to/vagrant/exec/vagrant /usr/local/bin/vagrant +</pre></div> +<p>When you want to switch back to the official Vagrant version, simply remove the symlink.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/installation/source.html" class="_attribution-link">https://www.vagrantup.com/docs/installation/source.html</a> + </p> +</div> diff --git a/devdocs/vagrant/installation%2Funinstallation.html b/devdocs/vagrant/installation%2Funinstallation.html new file mode 100644 index 00000000..f727b004 --- /dev/null +++ b/devdocs/vagrant/installation%2Funinstallation.html @@ -0,0 +1,13 @@ +<h1 id="uninstalling-vagrant"> Uninstalling Vagrant </h1> <p>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.</p> <h2 id="removing-the-vagrant-program"> Removing the Vagrant Program </h2> <p>Removing the Vagrant program will remove the <code>vagrant</code> binary and all dependencies from your machine. After uninstalling the program, you can always <a href="index">reinstall</a> again using standard methods.</p> <p>On <strong>Windows</strong></p> <blockquote> <p>Uninstall using the add/remove programs section of the control panel</p> </blockquote> <p>On <strong>Mac OS X</strong>:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">rm -rf /opt/vagrant +rm -f /usr/local/bin/vagrant +sudo pkgutil --forget com.vagrant.vagrant +</pre></div> +<p>On <strong>Linux</strong>:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">rm -rf /opt/vagrant +rm -f /usr/bin/vagrant +</pre></div> +<h2 id="removing-user-data"> Removing User Data </h2> <p>Removing the user data will remove all <a href="../boxes">boxes</a>, <a href="../plugins/index">plugins</a>, 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.</p> <p>On all platforms, remove the <code>~/.vagrant.d</code> directory to delete the user data. When debugging, the Vagrant support team may ask you to remove this directory. Before removing this directory, please make a backup.</p> <p>Running Vagrant will automatically regenerate any data necessary to run, so it is safe to remove the user data at any time.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/installation/uninstallation.html" class="_attribution-link">https://www.vagrantup.com/docs/installation/uninstallation.html</a> + </p> +</div> diff --git a/devdocs/vagrant/installation%2Fupgrading-from-1-0.html b/devdocs/vagrant/installation%2Fupgrading-from-1-0.html new file mode 100644 index 00000000..27ded35d --- /dev/null +++ b/devdocs/vagrant/installation%2Fupgrading-from-1-0.html @@ -0,0 +1,6 @@ +<h1 id="upgrading-from-vagrant-1-0-x"> Upgrading From Vagrant 1.0.x </h1> <p>The upgrade process from 1.0.x to 1.x is straightforward. Vagrant is quite <a href="backwards-compatibility">backwards compatible</a> 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.</p> <p>As the <a href="backwards-compatibility">backwards compatibility</a> page says, <strong>Vagrant 1.0.x plugins will not work with Vagrant 1.1+</strong>. 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.</p> <p>It is recommended you remove <em>all</em> plugins before upgrading, and then slowly add back the plugins. This usually makes for a smoother upgrade process.</p> <blockquote class="alert alert-warning" role="alert"> <p><strong>If your version of Vagrant was installed via Rubygems</strong>, you must uninstall the old version prior to installing the package for the new version of Vagrant. The Rubygems installation is no longer supported.</p> </blockquote><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/installation/upgrading-from-1-0.html" class="_attribution-link">https://www.vagrantup.com/docs/installation/upgrading-from-1-0.html</a> + </p> +</div> diff --git a/devdocs/vagrant/installation%2Fupgrading.html b/devdocs/vagrant/installation%2Fupgrading.html new file mode 100644 index 00000000..92753ee5 --- /dev/null +++ b/devdocs/vagrant/installation%2Fupgrading.html @@ -0,0 +1,7 @@ +<h1 id="upgrading-vagrant"> Upgrading Vagrant </h1> <p>If you are upgrading from Vagrant 1.0.x, please read the <a href="upgrading-from-1-0">specific page dedicated to that</a>. This page covers upgrading Vagrant in general during the 1.x series.</p> <p>Vagrant upgrades during the 1.x release series are straightforward:</p> <ol> <li> +<a href="https://www.vagrantup.com/downloads.html">Download</a> the new package </li> <li>Install it over the existing package </li> </ol> <p>The installers will properly overwrite and remove old files. It is recommended that no other Vagrant processes are running during the upgrade process.</p> <p>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 <a href="backwards-compatibility">continue to work</a>, newer Vagrantfiles may have backwards incompatible changes until 2.0 final.</p> <blockquote class="alert alert-info alert-block"> <p><strong>Run into troubles upgrading?</strong> Please <a href="https://github.com/hashicorp/vagrant/issues" class="alert-link">report an issue</a> if you run into problems upgrading. Upgrades are meant to be a smooth process and we consider it a bug if it was not.</p> </blockquote><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/installation/upgrading.html" class="_attribution-link">https://www.vagrantup.com/docs/installation/upgrading.html</a> + </p> +</div> diff --git a/devdocs/vagrant/metadata b/devdocs/vagrant/metadata new file mode 100644 index 00000000..b8dab5f1 --- /dev/null +++ b/devdocs/vagrant/metadata @@ -0,0 +1,2 @@ +(1 (name . "Vagrant") (slug . "vagrant") (type . "simple") (links (home . "https://www.vagrantup.com/") (code . "https://github.com/mitchellh/vagrant")) (release . "2.2.0") (mtime . 1541375199) (db_size . 620133) (attribution . "© 2010–2018 Mitchell Hashimoto<br> + Licensed under the MPL 2.0 License."))
\ No newline at end of file diff --git a/devdocs/vagrant/multi-machine%2Findex.html b/devdocs/vagrant/multi-machine%2Findex.html new file mode 100644 index 00000000..f9da77ef --- /dev/null +++ b/devdocs/vagrant/multi-machine%2Findex.html @@ -0,0 +1,36 @@ +<h1 id="multi-machine"> Multi-Machine </h1> <p>Vagrant is able to define and control multiple guest machines per Vagrantfile. This is known as a "multi-machine" environment.</p> <p>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:</p> <ul> <li>Accurately modeling a multi-server production topology, such as separating a web and database server. </li> <li>Modeling a distributed system and how they interact with each other. </li> <li>Testing an interface, such as an API to a service component. </li> <li>Disaster-case testing: machines dying, network partitions, slow networks, inconsistent world views, etc. </li> </ul> <p>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.</p> <p>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.</p> <h2 id="defining-multiple-machines"> Defining Multiple Machines </h2> <p>Multiple machines are defined within the same project <a href="../vagrantfile/index">Vagrantfile</a> using the <code>config.vm.define</code> method call. This configuration directive is a little funny, because it creates a Vagrant configuration within a configuration. An example shows this best:</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<p>As you can see, <code>config.vm.define</code> takes a block with another variable. This variable, such as <code>web</code> above, is the <em>exact</em> same as the <code>config</code> variable, except any configuration of the inner variable applies only to the machine being defined. Therefore, any configuration on <code>web</code> will only affect the <code>web</code> machine.</p> <p>And importantly, you can continue to use the <code>config</code> object as well. The configuration object is loaded and merged before the machine-specific configuration, just like other Vagrantfiles within the <a href="../vagrantfile/index#load-order">Vagrantfile load order</a>.</p> <p>If you are familiar with programming, this is similar to how languages have different variable scopes.</p> <p>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:</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<p>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.</p> <p>If you want to apply a slightly different configuration to multiple machines, see <a href="../vagrantfile/tips#loop-over-vm-definitions">this tip</a>.</p> <h2 id="controlling-multiple-machines"> Controlling Multiple Machines </h2> <p>The moment more than one machine is defined within a Vagrantfile, the usage of the various <code>vagrant</code> commands changes slightly. The change should be mostly intuitive.</p> <p>Commands that only make sense to target a single machine, such as <code>vagrant ssh</code>, now <em>require</em> the name of the machine to control. Using the example above, you would say <code>vagrant ssh web</code> or <code>vagrant ssh db</code>.</p> <p>Other commands, such as <code>vagrant up</code>, operate on <em>every</em> machine by default. So if you ran <code>vagrant up</code>, Vagrant would bring up both the web and DB machine. You could also optionally be specific and say <code>vagrant up web</code> or <code>vagrant up db</code>.</p> <p>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 <code>leader</code> machine as well as a <code>follower0</code>, <code>follower1</code>, <code>follower2</code>, etc. If you want to bring up all the followers but not the leader, you can just do <code>vagrant up /follower[0-9]/</code>. If Vagrant sees a machine name within forward slashes, it assumes you are using a regular expression.</p> <h2 id="communication-between-machines"> Communication Between Machines </h2> <p>In order to facilitate communication within machines in a multi-machine setup, the various <a href="../networking/index">networking</a> options should be used. In particular, the <a href="../networking/private_network">private network</a> can be used to make a private network between multiple machines and the host.</p> <h2 id="specifying-a-primary-machine"> Specifying a Primary Machine </h2> <p>You can also specify a <em>primary machine</em>. The primary machine will be the default machine used when a specific machine in a multi-machine environment is not specified.</p> <p>To specify a default machine, just mark it primary when defining it. Only one primary machine may be specified.</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.define "web", primary: true do |web| + # ... +end +</pre></div> +<h2 id="autostart-machines"> Autostart Machines </h2> <p>By default in a multi-machine environment, <code>vagrant up</code> will start all of the defined machines. The <code>autostart</code> setting allows you to tell Vagrant to <em>not</em> start specific machines. Example:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.define "web" +config.vm.define "db" +config.vm.define "db_follower", autostart: false +</pre></div> +<p>When running <code>vagrant up</code> 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 <code>vagrant up db_follower</code>.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/multi-machine/" class="_attribution-link">https://www.vagrantup.com/docs/multi-machine/</a> + </p> +</div> diff --git a/devdocs/vagrant/multi-machine.html b/devdocs/vagrant/multi-machine.html new file mode 100644 index 00000000..d8ecf760 --- /dev/null +++ b/devdocs/vagrant/multi-machine.html @@ -0,0 +1,36 @@ +<h1 id="multi-machine"> Multi-Machine </h1> <p>Vagrant is able to define and control multiple guest machines per Vagrantfile. This is known as a "multi-machine" environment.</p> <p>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:</p> <ul> <li>Accurately modeling a multi-server production topology, such as separating a web and database server. </li> <li>Modeling a distributed system and how they interact with each other. </li> <li>Testing an interface, such as an API to a service component. </li> <li>Disaster-case testing: machines dying, network partitions, slow networks, inconsistent world views, etc. </li> </ul> <p>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.</p> <p>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.</p> <h2 id="defining-multiple-machines"> Defining Multiple Machines </h2> <p>Multiple machines are defined within the same project <a href="vagrantfile/index">Vagrantfile</a> using the <code>config.vm.define</code> method call. This configuration directive is a little funny, because it creates a Vagrant configuration within a configuration. An example shows this best:</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<p>As you can see, <code>config.vm.define</code> takes a block with another variable. This variable, such as <code>web</code> above, is the <em>exact</em> same as the <code>config</code> variable, except any configuration of the inner variable applies only to the machine being defined. Therefore, any configuration on <code>web</code> will only affect the <code>web</code> machine.</p> <p>And importantly, you can continue to use the <code>config</code> object as well. The configuration object is loaded and merged before the machine-specific configuration, just like other Vagrantfiles within the <a href="vagrantfile/index#load-order">Vagrantfile load order</a>.</p> <p>If you are familiar with programming, this is similar to how languages have different variable scopes.</p> <p>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:</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<p>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.</p> <p>If you want to apply a slightly different configuration to multiple machines, see <a href="vagrantfile/tips#loop-over-vm-definitions">this tip</a>.</p> <h2 id="controlling-multiple-machines"> Controlling Multiple Machines </h2> <p>The moment more than one machine is defined within a Vagrantfile, the usage of the various <code>vagrant</code> commands changes slightly. The change should be mostly intuitive.</p> <p>Commands that only make sense to target a single machine, such as <code>vagrant ssh</code>, now <em>require</em> the name of the machine to control. Using the example above, you would say <code>vagrant ssh web</code> or <code>vagrant ssh db</code>.</p> <p>Other commands, such as <code>vagrant up</code>, operate on <em>every</em> machine by default. So if you ran <code>vagrant up</code>, Vagrant would bring up both the web and DB machine. You could also optionally be specific and say <code>vagrant up web</code> or <code>vagrant up db</code>.</p> <p>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 <code>leader</code> machine as well as a <code>follower0</code>, <code>follower1</code>, <code>follower2</code>, etc. If you want to bring up all the followers but not the leader, you can just do <code>vagrant up /follower[0-9]/</code>. If Vagrant sees a machine name within forward slashes, it assumes you are using a regular expression.</p> <h2 id="communication-between-machines"> Communication Between Machines </h2> <p>In order to facilitate communication within machines in a multi-machine setup, the various <a href="networking/index">networking</a> options should be used. In particular, the <a href="networking/private_network">private network</a> can be used to make a private network between multiple machines and the host.</p> <h2 id="specifying-a-primary-machine"> Specifying a Primary Machine </h2> <p>You can also specify a <em>primary machine</em>. The primary machine will be the default machine used when a specific machine in a multi-machine environment is not specified.</p> <p>To specify a default machine, just mark it primary when defining it. Only one primary machine may be specified.</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.define "web", primary: true do |web| + # ... +end +</pre></div> +<h2 id="autostart-machines"> Autostart Machines </h2> <p>By default in a multi-machine environment, <code>vagrant up</code> will start all of the defined machines. The <code>autostart</code> setting allows you to tell Vagrant to <em>not</em> start specific machines. Example:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.define "web" +config.vm.define "db" +config.vm.define "db_follower", autostart: false +</pre></div> +<p>When running <code>vagrant up</code> 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 <code>vagrant up db_follower</code>.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/multi-machine" class="_attribution-link">https://www.vagrantup.com/docs/multi-machine</a> + </p> +</div> diff --git a/devdocs/vagrant/networking%2Fbasic_usage.html b/devdocs/vagrant/networking%2Fbasic_usage.html new file mode 100644 index 00000000..1b24e0f6 --- /dev/null +++ b/devdocs/vagrant/networking%2Fbasic_usage.html @@ -0,0 +1,11 @@ +<h1 id="basic-usage-of-networking"> Basic Usage of Networking </h1> <p>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.</p> <h2 id="configuration"> Configuration </h2> <p>All networks are configured within your <a href="../vagrantfile/index">Vagrantfile</a> using the <code>config.vm.network</code> method call. For example, the Vagrantfile below defines some port forwarding:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + # ... + config.vm.network "forwarded_port", guest: 80, host: 8080 +end +</pre></div> +<p>Every network type has an identifier such as <code>"forwarded_port"</code> 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.</p> <h2 id="multiple-networks"> Multiple Networks </h2> <p>Multiple networks can be defined by having multiple <code>config.vm.network</code> calls within the Vagrantfile. The exact meaning of this can differ for each <a href="../providers/index">provider</a>, but in general the order specifies the order in which the networks are enabled.</p> <h2 id="enabling-networks"> Enabling Networks </h2> <p>Networks are automatically configured and enabled after they've been defined in the Vagrantfile as part of the <code>vagrant up</code> or <code>vagrant reload</code> process.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/networking/basic_usage.html" class="_attribution-link">https://www.vagrantup.com/docs/networking/basic_usage.html</a> + </p> +</div> diff --git a/devdocs/vagrant/networking%2Fforwarded_ports.html b/devdocs/vagrant/networking%2Fforwarded_ports.html new file mode 100644 index 00000000..1cef787c --- /dev/null +++ b/devdocs/vagrant/networking%2Fforwarded_ports.html @@ -0,0 +1,30 @@ +<h1 id="forwarded-ports"> Forwarded Ports </h1> <p><strong>Network identifier: <code>forwarded_port</code></strong></p> <p>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.</p> <p>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 <code>localhost:8080</code> and browse the website, while all actual network data is being sent to the guest.</p> <h2 id="defining-a-forwarded-port"> Defining a Forwarded Port </h2> <p>The forwarded port configuration expects two parameters, the port on the guest and the port on the host. Example:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.network "forwarded_port", guest: 80, host: 8080 +end +</pre></div> +<p>This will allow accessing port 80 on the guest via port 8080 on the host.</p> <p>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 <code>guest_ip</code> and <code>host_ip</code> settings below.</p> <h2 id="options-reference"> Options Reference </h2> <p>This is a complete list of the options that are available for forwarded ports. Only the <code>guest</code> and <code>host</code> options are required. Below this section, there are more detailed examples of using these options.</p> <ul> <li> +<p><a href="#auto_correct"><code>auto_correct</code></a> (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.</p> </li> <li> +<p><a href="#guest"><code>guest</code></a> (int) - The port on the guest that you want to be exposed on the host. This can be any port.</p> </li> <li> +<p><a href="#guest_ip"><code>guest_ip</code></a> (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.</p> </li> <li> +<p><a href="#host"><code>host</code></a> (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).</p> </li> <li> +<p><a href="#host_ip"><code>host_ip</code></a> (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.</p> </li> <li> +<p><a href="#protocol"><code>protocol</code></a> (string) - Either "udp" or "tcp". This specifies the protocol that will be allowed through the forwarded port. By default this is "tcp".</p> </li> <li> +<p><a href="#id"><code>id</code></a> (string) - Name of the rule (can be visible in VirtualBox). By default this is "protocol""guest" (example : "tcp123").</p> </li> </ul> <h2 id="forwarded-port-protocols"> Forwarded Port Protocols </h2> <p>By default, any defined port will only forward the TCP protocol. As an optional third parameter, you may specify <code>protocol: 'udp'</code> 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:</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<h2 id="port-collisions-and-correction"> Port Collisions and Correction </h2> <p>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.</p> <p>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.</p> <p>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:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.network "forwarded_port", guest: 80, host: 8080, + auto_correct: true +end +</pre></div> +<p>The final <code>:auto_correct</code> parameter set to true tells Vagrant to auto correct any collisions. During a <code>vagrant up</code> or <code>vagrant reload</code>, Vagrant will output information about any collisions detections and auto corrections made, so you can take notice and act accordingly.</p> <p>You can define allowed port range assignable by Vagrant when port collision is detected via <a href="../vagrantfile/machine_settings">config.vm.usable_port_range</a> property.</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.usable_port_range = 8000..8999 +end +</pre></div><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/networking/forwarded_ports.html" class="_attribution-link">https://www.vagrantup.com/docs/networking/forwarded_ports.html</a> + </p> +</div> diff --git a/devdocs/vagrant/networking%2Findex.html b/devdocs/vagrant/networking%2Findex.html new file mode 100644 index 00000000..1eb374ad --- /dev/null +++ b/devdocs/vagrant/networking%2Findex.html @@ -0,0 +1,6 @@ +<h1 id="networking"> Networking </h1> <p>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.</p> <p>The high-level networking options are meant to define an abstraction that works across multiple <a href="../providers/index">providers</a>. 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.</p> <p>You should first read the <a href="basic_usage">basic usage</a> page and then continue by reading the documentation for a specific networking primitive by following the navigation to the left.</p> <h2 id="advanced-configuration"> Advanced Configuration </h2> <p>In some cases, these options are <em>too</em> high-level, and you may want to more finely tune and configure the network interfaces of the underlying machine. Most providers expose <a href="../providers/configuration">provider-specific configuration</a> to do this, so please read the documentation for your specific provider to see what options are available.</p> <blockquote class="alert alert-info"> <p><strong>For beginners:</strong> 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.</p> </blockquote><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/networking/" class="_attribution-link">https://www.vagrantup.com/docs/networking/</a> + </p> +</div> diff --git a/devdocs/vagrant/networking%2Fprivate_network.html b/devdocs/vagrant/networking%2Fprivate_network.html new file mode 100644 index 00000000..e88ce9e1 --- /dev/null +++ b/devdocs/vagrant/networking%2Fprivate_network.html @@ -0,0 +1,31 @@ +<h1 id="private-networks"> Private Networks </h1> <p><strong>Network identifier: <code>private_network</code></strong></p> <p>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 <a href="https://en.wikipedia.org/wiki/Private_network#Private_IPv4_address_spaces">private address space</a>.</p> <p>Multiple machines within the same private network (also usually with the restriction that they're backed by the same <a href="../providers/index">provider</a>) can communicate with each other on private networks.</p> <blockquote class="alert alert-info"> <p><strong>Guest operating system support.</strong> 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.</p> </blockquote> +<h2 id="dhcp"> DHCP </h2> <p>The easiest way to use a private network is to allow the IP to be assigned via DHCP.</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.network "private_network", type: "dhcp" +end +</pre></div> +<p>This will automatically assign an IP address from the reserved address space. The IP address can be determined by using <code>vagrant ssh</code> to SSH into the machine and using the appropriate command line tool to find the IP, such as <code>ifconfig</code>.</p> <h2 id="static-ip"> Static IP </h2> <p>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:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.network "private_network", ip: "192.168.50.4" +end +</pre></div> +<p>It is up to the users to make sure that the static IP does not collide with any other machines on the same network.</p> <p>While you can choose any IP you would like, you <em>should</em> use an IP from the <a href="https://en.wikipedia.org/wiki/Private_network#Private_IPv4_address_spaces">reserved private address space</a>. These IPs are guaranteed to never be publicly routable, and most routers actually block traffic from going to them from the outside world.</p> <p>For some operating systems, additional configuration options for the static IP address are available such as setting the default gateway or MTU.</p> <blockquote class="alert alert-warning"> <p><strong>Warning!</strong> Do not choose an IP that overlaps with any other IP space on your system. This can cause the network to not be reachable.</p> </blockquote> +<h2 id="ipv6"> IPv6 </h2> <p>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:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.network "private_network", ip: "fde4:8dba:82e1::c4" +end +</pre></div> +<p>This will assign that IP to the machine. The entire <code>/64</code> subnet will be reserved. Please make sure to use the reserved local addresses approved for IPv6.</p> <p>You can also modify the prefix length by changing the <code>netmask</code> option (defaults to 64):</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.network "private_network", + ip: "fde4:8dba:82e1::c4", + netmask: "96" +end +</pre></div> +<p>IPv6 supports for private networks was added in Vagrant 1.7.5 and may not work with every provider.</p> <h2 id="disable-auto-configuration"> Disable Auto-Configuration </h2> <p>If you want to manually configure the network interface yourself, you can disable Vagrant's auto-configure feature by specifying <code>auto_config</code>:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.network "private_network", ip: "192.168.50.4", + auto_config: false +end +</pre></div> +<p>If you already started the Vagrant environment before setting <code>auto_config</code>, the files it initially placed there will stay there. You will have to remove those files manually or destroy and recreate the machine.</p> <p>The files created by Vagrant depend on the OS. For example, for many Linux distros, this is <code>/etc/network/interfaces</code>. In general you should look in the normal location that network interfaces are configured for your distro.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/networking/private_network.html" class="_attribution-link">https://www.vagrantup.com/docs/networking/private_network.html</a> + </p> +</div> diff --git a/devdocs/vagrant/networking%2Fpublic_network.html b/devdocs/vagrant/networking%2Fpublic_network.html new file mode 100644 index 00000000..54329bd4 --- /dev/null +++ b/devdocs/vagrant/networking%2Fpublic_network.html @@ -0,0 +1,63 @@ +<h1 id="public-networks"> Public Networks </h1> <p><strong>Network identifier: <code>public_network</code></strong></p> <p>Vagrant public networks are less private than private networks, and the exact meaning actually varies from <a href="../providers/index">provider to provider</a>, hence the ambiguous definition. The idea is that while <a href="private_network">private networks</a> should never allow the general public access to your machine, public networks can.</p> <blockquote class="alert alert-info"> <p><strong>Confused?</strong> We kind of are, too. It is likely that public networks will be replaced by <code>:bridged</code> 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.</p> </blockquote> +<blockquote class="alert alert-warning"> <p><strong>Warning!</strong> 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 <em>all</em> potential security implications and review the <a href="../boxes/base">default box configuration</a> to identify potential security risks.</p> </blockquote> +<h2 id="dhcp"> DHCP </h2> <p>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:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.network "public_network" +end +</pre></div> +<p>When DHCP is used, the IP can be determined by using <code>vagrant ssh</code> to SSH into the machine and using the appropriate command line tool to find the IP, such as <code>ifconfig</code>.</p> <h3 id="using-the-dhcp-assigned-default-route"> Using the DHCP Assigned Default Route </h3> <p>Some cases require the DHCP assigned default route to be untouched. In these cases one may specify the <code>use_dhcp_assigned_default_route</code> option. As an example:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.network "public_network", + use_dhcp_assigned_default_route: true +end +</pre></div> +<h2 id="static-ip"> Static IP </h2> <p>Depending on your setup, you may wish to manually set the IP of your bridged interface. To do so, add a <code>:ip</code> clause to the network definition.</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.network "public_network", ip: "192.168.0.17" +</pre></div> +<h2 id="default-network-interface"> Default Network Interface </h2> <p>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 <code>:bridge</code> clause to the network definition.</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.network "public_network", bridge: "en1: Wi-Fi (AirPort)" +</pre></div> +<p>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.</p> <p>With some providers, it is possible to specify a list of adapters to bridge against:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.network "public_network", bridge: [ + "en1: Wi-Fi (AirPort)", + "en6: Broadcom NetXtreme Gigabit Ethernet Controller", +] +</pre></div> +<p>In this example, the first network adapter that exists and can successfully be bridge will be used.</p> <h2 id="disable-auto-configuration"> Disable Auto-Configuration </h2> <p>If you want to manually configure the network interface yourself, you can disable auto-configuration by specifying <code>auto_config</code>:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.network "public_network", auto_config: false +end +</pre></div> +<p>Then the shell provisioner can be used to configure the ip of the interface:</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<h2 id="default-router"> Default Router </h2> <p>Depending on your setup, you may wish to manually override the default router configuration. This is required if you need access the Vagrant box from other networks over the public network. To do so, you can use a shell provisioner script:</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<p>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.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/networking/public_network.html" class="_attribution-link">https://www.vagrantup.com/docs/networking/public_network.html</a> + </p> +</div> diff --git a/devdocs/vagrant/other%2Fdebugging.html b/devdocs/vagrant/other%2Fdebugging.html new file mode 100644 index 00000000..a8e6eb8a --- /dev/null +++ b/devdocs/vagrant/other%2Fdebugging.html @@ -0,0 +1,16 @@ +<h1 id="debugging"> Debugging </h1> <p>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.</p> <p>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.</p> <blockquote class="alert alert-danger" role="alert"> <p><strong>Scan for sensitive information!</strong> 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.</p> </blockquote> <blockquote class="alert alert-warning" role="alert"> <p><strong>Submit debug logs using GitHub Gist.</strong> If you plan on submitting a bug report or issue that includes debug-level logs, please use a service like <a href="https://gist.github.com">Gist</a>. <strong>Do not</strong> paste the raw debug logs into an issue as it makes it very difficult to scroll and parse the information.</p> </blockquote> <p>To enable detailed logging, set the <code>VAGRANT_LOG</code> environmental variable to the desired log level name, which is one of <code>debug</code> (loud), <code>info</code> (normal), <code>warn</code> (quiet), and <code>error</code> (very quiet). When asking for support, please set this to <code>debug</code>. When troubleshooting your own issues, you should start with <code>info</code>, which is much quieter, but contains important information about the behavior of Vagrant.</p> <p>On Linux and Mac systems, this can be done by prepending the <code>vagrant</code> command with an environmental variable declaration:</p> <div class="highlight"><pre class="highlight plaintext">$ VAGRANT_LOG=info vagrant up +</pre></div> +<p>On Windows, multiple steps are required:</p> <div class="highlight"><pre class="highlight plaintext">$ set VAGRANT_LOG=info +$ vagrant up +</pre></div> +<p>You can also get the debug level output using the <code>--debug</code> command line option. For example:</p> <div class="highlight"><pre class="highlight plaintext">$ vagrant up --debug +</pre></div> +<p>On Linux and Mac, if you are saving the output to a file, you may need to redirect stderr and stdout using <code>&></code>:</p> <div class="highlight"><pre class="highlight plaintext">$ vagrant up --debug &> vagrant.log +</pre></div> +<p>On Windows in PowerShell (outputs to log and screen):</p> <div class="highlight"><pre class="highlight plaintext">$ vagrant up --debug 2>&1 | Tee-Object -FilePath ".\vagrant.log" +</pre></div><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/other/debugging.html" class="_attribution-link">https://www.vagrantup.com/docs/other/debugging.html</a> + </p> +</div> diff --git a/devdocs/vagrant/other%2Fenvironmental-variables.html b/devdocs/vagrant/other%2Fenvironmental-variables.html new file mode 100644 index 00000000..b3b2f155 --- /dev/null +++ b/devdocs/vagrant/other%2Fenvironmental-variables.html @@ -0,0 +1,6 @@ +<h1 id="environmental-variables"> Environmental Variables </h1> <p>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.</p> <h2 id="vagrant_alias_file"> <code>VAGRANT_ALIAS_FILE</code> </h2> <p><code>VAGRANT_ALIAS_FILE</code> can be set to change the file where Vagrant aliases are defined. By default, this is set to <code>~/.vagrant.d/aliases</code>.</p> <h2 id="vagrant_debug_launcher"> <code>VAGRANT_DEBUG_LAUNCHER</code> </h2> <p>For performance reasons, especially for Windows users, Vagrant uses a static binary to launch the actual Vagrant process. If you have <em>very</em> early issues when launching Vagrant from the official installer, you can specify the <code>VAGRANT_DEBUG_LAUNCHER</code> environment variable to output debugging information about the launch process.</p> <h2 id="vagrant_default_provider"> <code>VAGRANT_DEFAULT_PROVIDER</code> </h2> <p>This configures the default provider Vagrant will use.</p> <p>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 <em>new</em> Vagrant environments. Existing Vagrant environments will continue to use the provider they came <code>up</code> with. Once you <code>vagrant destroy</code> existing environments, this will take effect.</p> <h2 id="vagrant_default_template"> <code>VAGRANT_DEFAULT_TEMPLATE</code> </h2> <p>This configures the template used by <code>vagrant init</code> when the <code>--template</code> option is not provided.</p> <h2 id="vagrant_preferred_providers"> <code>VAGRANT_PREFERRED_PROVIDERS</code> </h2> <p>This configures providers that Vagrant should prefer.</p> <p>Much like the <code>VAGRANT_DEFAULT_PROVIDER</code> this environment variable normally does not need to be set. By setting this you will instruct Vagrant to <em>prefer</em> providers defined in this environment variable for any <em>new</em> Vagrant environments. Existing Vagrant environments will continue to use the provider they came <code>up</code> with. Once you <code>vagrant destroy</code> existing environments, this will take effect. A single provider can be defined within this environment variable or a comma delimited list of providers.</p> <h2 id="vagrant_box_update_check_disable"> <code>VAGRANT_BOX_UPDATE_CHECK_DISABLE</code> </h2> <p>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 <code>config.vm.box_check_update</code>, but it can also be disabled globally setting <code>VAGRANT_BOX_UPDATE_CHECK_DISABLE</code> to any non-empty value.</p> <p>This option will not affect global box functions like <code>vagrant box update</code>.</p> <h2 id="vagrant_checkpoint_disable"> <code>VAGRANT_CHECKPOINT_DISABLE</code> </h2> <p>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 <code>VAGRANT_CHECKPOINT_DISABLE</code> to any non-empty value.</p> <p>If you use other HashiCorp tools like Packer and would prefer to configure this setting only once, you can set <code>CHECKPOINT_DISABLE</code> instead.</p> <h2 id="vagrant_cwd"> <code>VAGRANT_CWD</code> </h2> <p><code>VAGRANT_CWD</code> 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.</p> <p>This environmental variable is most commonly set when running Vagrant from a scripting environment in order to set the directory that Vagrant sees.</p> <h2 id="vagrant_dotfile_path"> <code>VAGRANT_DOTFILE_PATH</code> </h2> <p><code>VAGRANT_DOTFILE_PATH</code> 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 <code>.vagrant</code>. 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 <code>VAGRANT_DOTFILE_PATH</code> to <code>.vagrant-laptop</code> and <code>.vagrant-desktop</code> on the respective machines. (Remember to update your <code>.gitignore</code>!)</p> <h2 id="vagrant_home"> <code>VAGRANT_HOME</code> </h2> <p><code>VAGRANT_HOME</code> can be set to change the directory where Vagrant stores global state. By default, this is set to <code>~/.vagrant.d</code>. The Vagrant home directory is where things such as boxes are stored, so it can actually become quite large on disk.</p> <h2 id="vagrant_log"> <code>VAGRANT_LOG</code> </h2> <p><code>VAGRANT_LOG</code> specifies the verbosity of log messages from Vagrant. By default, Vagrant does not actively show any log messages.</p> <p>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.</p> <p>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.</p> <p>"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.</p> <p>"debug" output is <em>extremely</em> 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.</p> <h2 id="vagrant_no_color"> <code>VAGRANT_NO_COLOR</code> </h2> <p>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.</p> <p>The equivalent behavior can be achieved by using the <code>--no-color</code> flag on a command-by-command basis. This environmental variable is useful for setting this flag globally.</p> <h2 id="vagrant_force_color"> <code>VAGRANT_FORCE_COLOR</code> </h2> <p>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.</p> <p>The equivalent behavior can be achieved by using the <code>--color</code> flag on a command-by-command basis. This environmental variable is useful for setting this flag globally.</p> <h2 id="vagrant_no_plugins"> <code>VAGRANT_NO_PLUGINS</code> </h2> <p>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.</p> <p>Note that any <code>vagrant plugin</code> commands automatically do not load any plugins, so if you do install any unstable plugins, you can always use the <code>vagrant plugin</code> commands without having to worry.</p> <h2 id="vagrant_allow_plugin_source_errors"> <code>VAGRANT_ALLOW_PLUGIN_SOURCE_ERRORS</code> </h2> <p>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.</p> <h2 id="vagrant_install_local_plugins"> <code>VAGRANT_INSTALL_LOCAL_PLUGINS</code> </h2> <p>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.</p> <h2 id="vagrant_local_plugins_load"> <code>VAGRANT_LOCAL_PLUGINS_LOAD</code> </h2> <p>If this is set Vagrant will not stub the Vagrantfile when running <code>vagrant plugin</code> commands. When this environment variable is set the <code>--local</code> flag will not be required by <code>vagrant plugin</code> commands to enable local project plugins.</p> <h2 id="vagrant_no_parallel"> <code>VAGRANT_NO_PARALLEL</code> </h2> <p>If this is set, Vagrant will not perform any parallel operations (such as parallel box provisioning). All operations will be performed in serial.</p> <h2 id="vagrant_detected_os"> <code>VAGRANT_DETECTED_OS</code> </h2> <p>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.</p> <h2 id="vagrant_detected_arch"> <code>VAGRANT_DETECTED_ARCH</code> </h2> <p>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.</p> <h2 id="vagrant_winpty_disable"> <code>VAGRANT_WINPTY_DISABLE</code> </h2> <p>If this is set, Vagrant will <em>not</em> wrap interactive processes with winpty where required.</p> <h2 id="vagrant_prefer_system_bin"> <code>VAGRANT_PREFER_SYSTEM_BIN</code> </h2> <p>If this is set, Vagrant will prefer using utility executables (like <code>ssh</code> and <code>rsync</code>) from the local system instead of those vendored within the Vagrant installation.</p> <p>Vagrant will default to using a system provided <code>ssh</code> on Windows. This environment variable can also be used to disable that behavior to force Vagrant to use the embedded <code>ssh</code> executable by setting it to <code>0</code>.</p> <h2 id="vagrant_skip_subprocess_jailbreak"> <code>VAGRANT_SKIP_SUBPROCESS_JAILBREAK</code> </h2> <p>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.</p> <p>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 <code>VAGRANT_SKIP_SUBPROCESS_JAILBREAK</code>.</p> <h2 id="vagrant_vagrantfile"> <code>VAGRANT_VAGRANTFILE</code> </h2> <p>This specifies the filename of the Vagrantfile that Vagrant searches for. By default, this is "Vagrantfile". Note that this is <em>not</em> a file path, but just a filename.</p> <p>This environmental variable is commonly used in scripting environments where a single folder may contain multiple Vagrantfiles representing different configurations.</p> <h2 id="vagrant_disable_vboxsymlinkcreate"> <code>VAGRANT_DISABLE_VBOXSYMLINKCREATE</code> </h2> <p>If set, this will disable the ability to create symlinks with all virtualbox shared folders. Defaults to true if the option is not set. This can be overridden on a per-folder basis within your Vagrantfile config by settings the <code>SharedFoldersEnableSymlinksCreate</code> option to true.</p> <h2 id="vagrant_enable_resolv_replace"> <code>VAGRANT_ENABLE_RESOLV_REPLACE</code> </h2> <p>Use the Ruby Resolv library in place of the libc resolver.</p> <h2 id="vagrant_disable_resolv_replace"> <code>VAGRANT_DISABLE_RESOLV_REPLACE</code> </h2> <p>Vagrant can optionally use the Ruby Resolv library in place of the libc resolver. This can be disabled setting this environment variable.</p> <h2 id="vagrant_powershell_version_detection_timeout"> <code>VAGRANT_POWERSHELL_VERSION_DETECTION_TIMEOUT</code> </h2> <p>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.</p> <p>When setting this environment variable, its value will be in seconds. By default, it will use 30 seconds as a timeout.</p> <h2 id="vagrant_use_vagrant_triggers"> <code>VAGRANT_USE_VAGRANT_TRIGGERS</code> </h2> <p>Vagrant will not display the warning about disabling the core trigger feature if the community plugin is installed.</p> <h2 id="vagrant_ignore_winrm_plugin"> <code>VAGRANT_IGNORE_WINRM_PLUGIN</code> </h2> <p>Vagrant will not display warning when <code>vagrant-winrm</code> plugin is installed.</p> <h2 id="vagrant_user_agent_provisional_string"> <code>VAGRANT_USER_AGENT_PROVISIONAL_STRING</code> </h2> <p>Vagrant will append the contents of this variable to the default user agent header.</p> <h2 id="vagrant_is_hyperv_admin"> <code>VAGRANT_IS_HYPERV_ADMIN</code> </h2> <p>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.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/other/environmental-variables.html" class="_attribution-link">https://www.vagrantup.com/docs/other/environmental-variables.html</a> + </p> +</div> diff --git a/devdocs/vagrant/other%2Findex.html b/devdocs/vagrant/other%2Findex.html new file mode 100644 index 00000000..050f6271 --- /dev/null +++ b/devdocs/vagrant/other%2Findex.html @@ -0,0 +1,8 @@ +<h1 id="other"> Other </h1> <p>This section covers other information that does not quite fit under the other categories.</p> <ul> <li> +<a href="debugging">Debugging</a> </li> <li> +<a href="environmental-variables">Environment Variables</a> </li> </ul><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/other/" class="_attribution-link">https://www.vagrantup.com/docs/other/</a> + </p> +</div> diff --git a/devdocs/vagrant/other%2Fwsl.html b/devdocs/vagrant/other%2Fwsl.html new file mode 100644 index 00000000..d5d3302f --- /dev/null +++ b/devdocs/vagrant/other%2Fwsl.html @@ -0,0 +1,22 @@ +<h1 id="vagrant-and-windows-subsystem-for-linux"> Vagrant and Windows Subsystem for Linux </h1> <p>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 <em>beta</em>.</p> <blockquote class="alert alert-warning"> <p><strong>Warning: Advanced Topic!</strong> 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.</p> </blockquote> +<h2 id="vagrant-installation"> Vagrant Installation </h2> <p>Vagrant <em>must</em> be installed within the Linux distribution used with WSL. While the <code>vagrant.exe</code> executable provided by the Vagrant Windows installation is accessible from within the WSL, it will not function as expected.</p> <p>Download the installer package for the Linux distribution from the releases page and install Vagrant.</p> <p>_<em>NOTE: When Vagrant is installed on the Windows system the version installed within the Linux distribution <em>must</em> match.</em></p> <h1 id="vagrant-usage"> Vagrant Usage </h1> <h2 id="windows-access"> Windows Access </h2> <p>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 <code>VAGRANT_WSL_ENABLE_WINDOWS_ACCESS</code> environment variable:</p> <div class="highlight"><pre class="highlight plaintext">$ export VAGRANT_WSL_ENABLE_WINDOWS_ACCESS="1" +</pre></div> +<p>When Windows access is enabled Vagrant will automatically adjust <code>VAGRANT_HOME</code> to be located on the Windows host. This is required to ensure <code>VAGRANT_HOME</code> is located on a DrvFs file system.</p> <h2 id="path-modifications"> PATH modifications </h2> <p>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 <code>PATH</code> to allow Vagrant to access them.</p> <p>For example, when using the VirtualBox provider:</p> <div class="highlight"><pre class="highlight plaintext">export PATH="$PATH:/mnt/c/Program Files/Oracle/VirtualBox" +</pre></div> +<h2 id="synced-folders"> Synced Folders </h2> <p>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).</p> <h2 id="windows-access-1"> Windows Access </h2> <p>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: <code>VAGRANT_WSL_ENABLE_WINDOWS_ACCESS</code>. 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:</p> <div class="highlight"><pre class="highlight plaintext">$ export VAGRANT_WSL_ENABLE_WINDOWS_ACCESS="1" +</pre></div> +<p>This will enable Vagrant to access the Windows system outside of the WSL and properly interact with Windows executables. This will automatically modify the <code>VAGRANT_HOME</code> environment variable if it is not already defined, setting it to be within the user's home directory on Windows.</p> <p>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.</p> <p>Other useful WSL related environment variables:</p> <ul> <li> +<a href="#vagrant_wsl_windows_access_user"><code>VAGRANT_WSL_WINDOWS_ACCESS_USER</code></a> - Override current Windows username </li> <li> +<a href="#vagrant_wsl_disable_vagrant_home"><code>VAGRANT_WSL_DISABLE_VAGRANT_HOME</code></a> - Do not modify the <code>VAGRANT_HOME</code> variable </li> <li> +<a href="#vagrant_wsl_windows_access_user_home_path"><code>VAGRANT_WSL_WINDOWS_ACCESS_USER_HOME_PATH</code></a> - Custom Windows system home path </li> </ul> <p>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 <code>vagrant ssh</code>). When accessing Vagrant projects outside the WSL Vagrant will skip these permission checks when the project path is within the path defined in the <code>VAGRANT_WSL_WINDOWS_ACCESS_USER_HOME_PATH</code> environment variable. For example, if a user wants to run a Vagrant project from the WSL that is located at <code>C:\TestDir\vagrant-project</code>:</p> <div class="highlight"><pre class="highlight plaintext">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 +</pre></div> +<h2 id="using-docker"> Using Docker </h2> <p>The docker daemon cannot be run inside the Windows Subsystem for Linux. However, the daemon <em>can</em> 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:</p> <div class="highlight"><pre class="highlight plaintext">vagrant@vagrant-10:/mnt/c/Users/vagrant$ export DOCKER_HOST=tcp://127.0.0.1:2375 +</pre></div><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/other/wsl.html" class="_attribution-link">https://www.vagrantup.com/docs/other/wsl.html</a> + </p> +</div> diff --git a/devdocs/vagrant/plugins%2Faction-hooks.html b/devdocs/vagrant/plugins%2Faction-hooks.html new file mode 100644 index 00000000..69f78e05 --- /dev/null +++ b/devdocs/vagrant/plugins%2Faction-hooks.html @@ -0,0 +1,26 @@ +<h1 id="action-hooks"> Action Hooks </h1> <p>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.</p> <blockquote class="alert alert-warning"> <p><strong>Warning: Advanced Topic!</strong> Developing plugins is an advanced topic that only experienced Vagrant users who are reasonably comfortable with Ruby should approach.</p> </blockquote> +<h2 id="public-action-hooks"> Public Action Hooks </h2> <p>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.</p> <ul> <li> +<p><a href="#environment_plugins_loaded"><code>environment_plugins_loaded</code></a> - called after the plugins have been loaded, but before the configurations, provisioners, providers, etc. are loaded.</p> </li> <li> +<p><a href="#environment_load"><code>environment_load</code></a> - called after the environment and all configurations are fully loaded.</p> </li> <li> +<p><a href="#environment_unload"><code>environment_unload</code></a> - called after the environment is done being used. The environment should not be used in this hook.</p> </li> <li> +<p><a href="#machine_action_boot"><code>machine_action_boot</code></a> - called after the hypervisor has reported the machine was booted.</p> </li> <li> +<p><a href="#machine_action_config_validate"><code>machine_action_config_validate</code></a> - called after all <code>Vagrantfile</code>s have been loaded, merged, and validated.</p> </li> <li> +<p><a href="#machine_action_destroy"><code>machine_action_destroy</code></a> - called after the hypervisor has reported the virtual machine is down.</p> </li> <li> +<p><a href="#machine_action_halt"><code>machine_action_halt</code></a> - called after the hypervisor has moved the machine into a halted state (usually "stopped" but not "terminated").</p> </li> <li> +<p><a href="#machine_action_package"><code>machine_action_package</code></a> - called after Vagrant has successfully packaged a new box.</p> </li> <li> +<p><a href="#machine_action_provision"><code>machine_action_provision</code></a> - called after all provisioners have executed.</p> </li> <li> +<p><a href="#machine_action_read_state"><code>machine_action_read_state</code></a> - called after Vagrant has loaded state from disk and the hypervisor.</p> </li> <li> +<p><a href="#machine_action_reload"><code>machine_action_reload</code></a> - called after a virtual machine is reloaded (varies by hypervisor).</p> </li> <li> +<p><a href="#machine_action_resume"><code>machine_action_resume</code></a> - called after a virtual machine is moved from the halted to up state.</p> </li> <li> +<p><a href="#machine_action_run_command"><code>machine_action_run_command</code></a> - called after a command is executed on the machine.</p> </li> <li> +<p><a href="#machine_action_ssh"><code>machine_action_ssh</code></a> - called after an SSH connection has been established.</p> </li> <li> +<p><a href="#machine_action_ssh_run"><code>machine_action_ssh_run</code></a> - called after an SSH command is executed.</p> </li> <li> +<p><a href="#machine_action_start"><code>machine_action_start</code></a> - called after the machine has been started.</p> </li> <li> +<p><a href="#machine_action_suspend"><code>machine_action_suspend</code></a> - called after the machine has been suspended.</p> </li> <li> +<p><a href="#machine_action_sync_folders"><code>machine_action_sync_folders</code></a> - called after synced folders have been set up.</p> </li> <li> +<p><a href="#machine_action_up"><code>machine_action_up</code></a> - called after the machine has entered the up state.</p> </li> </ul> <h2 id="private-api"> Private API </h2> <p>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.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/plugins/action-hooks.html" class="_attribution-link">https://www.vagrantup.com/docs/plugins/action-hooks.html</a> + </p> +</div> diff --git a/devdocs/vagrant/plugins%2Fcommands.html b/devdocs/vagrant/plugins%2Fcommands.html new file mode 100644 index 00000000..cb46319a --- /dev/null +++ b/devdocs/vagrant/plugins%2Fcommands.html @@ -0,0 +1,43 @@ +<h1 id="plugin-development-commands"> Plugin Development: Commands </h1> <p>This page documents how to add new commands to Vagrant, invocable via <code>vagrant YOUR-COMMAND</code>. Prior to reading this, you should be familiar with the <a href="development-basics">plugin development basics</a>.</p> <blockquote class="alert alert-warning"> <p><strong>Warning: Advanced Topic!</strong> Developing plugins is an advanced topic that only experienced Vagrant users who are reasonably comfortable with Ruby should approach.</p> </blockquote> +<h2 id="definition-component"> Definition Component </h2> <p>Within the context of a plugin definition, new commands can be defined like so:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">command "foo" do + require_relative "command" + Command +end +</pre></div> +<p>Commands are defined with the <code>command</code> method, which takes as an argument the name of the command, in this case "foo." This means the command will be invocable via <code>vagrant foo</code>. Then the block argument returns a class that implements the <code>Vagrant.plugin(2, "command")</code> interface.</p> <p>You can also define <em>non-primary commands</em>. These commands do not show up in the <code>vagrant -h</code> output. They only show up if the user explicitly does a <code>vagrant list-commands</code> 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.</p> <p>To define a non-primary command:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">command("foo", primary: false) do + require_relative "command" + Command +end +</pre></div> +<h2 id="implementation"> Implementation </h2> <p>Implementations of commands should subclass <code>Vagrant.plugin(2, :command)</code>, 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: <code>execute</code>. Example:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">class Command < Vagrant.plugin(2, :command) + def execute + puts "Hello!" + 0 + end +end +</pre></div> +<p>The <code>execute</code> method is called when the command is invoked, and it should return the exit status (0 for success, anything else for error).</p> <p>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.</p> <h2 id="parsing-command-line-options"> Parsing Command-Line Options </h2> <p>The <code>parse_options</code> method is available which will parse the command line for you. It takes an <a href="http://ruby-doc.org/stdlib-1.9.3/libdoc/optparse/rdoc/OptionParser.html">OptionParser</a> as an argument, and adds some common elements to it such as the <code>--help</code> flag, automatically showing help if requested. View the API docs directly for more information.</p> <p>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 <code>destroy</code> command:</p> <div class="highlight"><pre class="highlight ruby" data-language="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) +</pre></div> +<h2 id="using-vagrant-machines"> Using Vagrant Machines </h2> <p>The <code>with_target_vms</code> 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 (<code>vagrant foo my-vm</code>), etc. If you need to do any manipulation of a Vagrant machine, including SSH access, this helper should be used.</p> <p>An example of using the helper, again pulled directly from the built-in <code>destroy</code> command:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">with_target_vms(argv, reverse: true) do |machine| + machine.action(:destroy) +end +</pre></div> +<p>In this case, it asks for the machines in reverse order and calls the destroy action on each of them. If a user says <code>vagrant destroy foo</code>, then the helper automatically only yields the <code>foo</code> 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.</p> <h2 id="using-the-raw-vagrant-environment"> Using the Raw Vagrant Environment </h2> <p>The raw loaded <code>Vagrant::Environment</code> object is available with the '@env' instance variable.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/plugins/commands.html" class="_attribution-link">https://www.vagrantup.com/docs/plugins/commands.html</a> + </p> +</div> diff --git a/devdocs/vagrant/plugins%2Fconfiguration.html b/devdocs/vagrant/plugins%2Fconfiguration.html new file mode 100644 index 00000000..b0e751f8 --- /dev/null +++ b/devdocs/vagrant/plugins%2Fconfiguration.html @@ -0,0 +1,85 @@ +<h1 id="plugin-development-configuration"> Plugin Development: Configuration </h1> <p>This page documents how to add new configuration options to Vagrant, settable with <code>config.YOURKEY</code> in Vagrantfiles. Prior to reading this, you should be familiar with the <a href="development-basics">plugin development basics</a>.</p> <blockquote class="alert alert-warning"> <p><strong>Warning: Advanced Topic!</strong> Developing plugins is an advanced topic that only experienced Vagrant users who are reasonably comfortable with Ruby should approach.</p> </blockquote> +<h2 id="definition-component"> Definition Component </h2> <p>Within the context of a plugin definition, new configuration keys can be defined like so:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config "foo" do + require_relative "config" + Config +end +</pre></div> +<p>Configuration keys are defined with the <code>config</code> 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 <code>config.foo</code> in Vagrantfiles. Then, the block argument returns a class that implements the <code>Vagrant.plugin(2, :config)</code> interface.</p> <h2 id="implementation"> Implementation </h2> <p>Implementations of configuration keys should subclass <code>Vagrant.plugin(2, :config)</code>, 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:</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<p>When using this configuration class, it looks like the following:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + # ... + + config.foo.widgets = 12 +end +</pre></div> +<p>Easy. The only odd thing is the <code>UNSET_VALUE</code> bits above. This is actually so that Vagrant can properly automatically merge multiple configurations. Merging is covered in the next section, and <code>UNSET_VALUE</code> will be explained there.</p> <h2 id="merging"> Merging </h2> <p>Vagrant works by loading <a href="../vagrantfile/index#load-order">multiple Vagrantfiles and merging them</a>. 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 <code>UNSET_VALUE</code> and set them onto the merged result.</p> <p>The reason <code>UNSET_VALUE</code> is used instead of Ruby's <code>nil</code> is because it is possible that you want the default to be some value, and the user actually wants to set the value to <code>nil</code>, and it is impossible for Vagrant to automatically determine whether the user set the instance variable, or if it was defaulted as nil.</p> <p>This merge logic is what you want almost every time. Hence, in the example above, <code>@widgets</code> is set to <code>UNSET_VALUE</code>. If we had two Vagrant configuration objects in the same file, then Vagrant would properly merge the follows. The example below shows this:</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<p>If this were placed in a Vagrantfile, after merging, the value of widgets would be "2".</p> <p>The <code>finalize!</code> method is called only once ever on the final configuration object in order to set defaults. If <code>finalize!</code> is called, that configuration will never be merged again, it is final. This lets you detect any <code>UNSET_VALUE</code> and set the proper default, as we do in the above example.</p> <p>Of course, sometimes you want custom merge logic. Let us say we wanted our widgets to be additive. We can override the <code>merge</code> method to do this:</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<p>In this case, we did not use <code>UNSET_VALUE</code> 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".</p> <h2 id="validation"> Validation </h2> <p>Configuration classes are also responsible for validating their own values. Vagrant will call the <code>validate</code> method to do this. An example validation method is shown below:</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<p>The validation method is given a <code>machine</code> 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.</p> <p>The <code>_detected_errors</code> 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.</p> <p>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.</p> <h2 id="accessing"> Accessing </h2> <p>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 <em>most</em> plugins expose an initializer like this:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">def initialize(machine, config) + @machine = machine + @config = config +end +</pre></div> +<p>When authoring a plugin, simply call <code>super</code> in your initialize function to setup these instance variables:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">def initialize(*) + super + + @config.is_now_available + # ...existing code +end + +def my_helper + @config.is_here_too +end +</pre></div> +<p>For examples, take a look at Vagrant's own internal plugins in the <code>plugins</code> folder in Vagrant's source on GitHub.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/plugins/configuration.html" class="_attribution-link">https://www.vagrantup.com/docs/plugins/configuration.html</a> + </p> +</div> diff --git a/devdocs/vagrant/plugins%2Fdevelopment-basics.html b/devdocs/vagrant/plugins%2Fdevelopment-basics.html new file mode 100644 index 00000000..bd12bb35 --- /dev/null +++ b/devdocs/vagrant/plugins%2Fdevelopment-basics.html @@ -0,0 +1,35 @@ +<h1 id="plugin-development-basics"> Plugin Development Basics </h1> <p>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.</p> <p>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.</p> <blockquote class="alert alert-warning"> <p><strong>Warning: Advanced Topic!</strong> Developing plugins is an advanced topic that only experienced Vagrant users who are reasonably comfortable with Ruby should approach.</p> </blockquote> +<p>Plugins are written using <a href="https://www.ruby-lang.org/en/">Ruby</a> and are packaged using <a href="https://rubygems.org/">RubyGems</a>. Familiarity with Ruby is required, but the <a href="packaging">packaging and distribution</a> section should help guide you to packaging your plugin into a RubyGem.</p> <h2 id="setup-and-workflow"> Setup and Workflow </h2> <p>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 <code>bundle gem</code> command.</p> <p>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:</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<p>This Gemfile gets "vagrant" for development. This allows you to <code>bundle exec vagrant</code> to run Vagrant with your plugin already loaded, so that you can test it manually that way.</p> <p>The only thing about this Gemfile that may stand out as odd is the "plugins" group and putting your plugin in that group. Because <code>vagrant plugin</code> 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.</p> <p>When you want to manually test your plugin, use <code>bundle exec vagrant</code> in order to run Vagrant with your plugin loaded (as we specified in the Gemfile).</p> <h2 id="plugin-definition"> Plugin Definition </h2> <p>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.</p> <p>A definition at the bare minimum looks like the following:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">class MyPlugin < Vagrant.plugin("2") + name "My Plugin" +end +</pre></div> +<p>A definition is a class that inherits from <code>Vagrant.plugin("2")</code>. 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")</p> <p><strong>The most critical feature of a plugin definition</strong> is that it must <em>always</em> 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.</p> <h2 id="plugin-components"> Plugin Components </h2> <p>Within the definition, a plugin advertises what components it adds to Vagrant. An example is shown below where a command and provisioner are added:</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<p>Let us go over the major pieces of what is going on here. Note from a general Ruby language perspective the above <em>should</em> be familiar. The syntax should not scare you. If it does, then please familiarize with Ruby further before attempting to write a plugin.</p> <p>The first thing to note is that individual components are defined by making a method call with the component name, such as <code>command</code> or <code>provisioner</code>. 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.</p> <p>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.</p> <p>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 <em>definition</em> is just plain Ruby that must always be forward compatible to future Vagrant versions.</p> <p>To repeat, <strong>the lazy loading aspect of plugin components is critical</strong> to the way Vagrant plugins work. All components must be lazily loaded and returned within their definition blocks.</p> <p>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.</p> <h2 id="error-handling"> Error Handling </h2> <p>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.</p> <p>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 <code>Vagrant::Errors::VagrantError</code>, then the <code>vagrant</code> command will output the message of the error in nice red text to the console and exit with an exit status of 1.</p> <p>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.</p> <p>Therefore, to fit into Vagrant's error handling mechanisms, subclass <code>VagrantError</code> and set a proper message on your exception. To see examples of this, look at Vagrant's <a href="https://github.com/hashicorp/vagrant/blob/master/lib/vagrant/errors.rb">built-in errors</a>.</p> <h2 id="console-input-and-output"> Console Input and Output </h2> <p>Most plugins are likely going to want to do some sort of input/output. Plugins should <em>never</em> use Ruby's built-in <code>puts</code> or <code>gets</code> 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.</p> <p>A UI object is available on every <code>Vagrant::Environment</code> via the <code>ui</code> property and is exposed within every middleware environment via the <code>:ui</code> key. UI objects have <a href="https://github.com/hashicorp/vagrant/blob/master/lib/vagrant/ui.rb">decent documentation</a> within the comments of their source.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/plugins/development-basics.html" class="_attribution-link">https://www.vagrantup.com/docs/plugins/development-basics.html</a> + </p> +</div> diff --git a/devdocs/vagrant/plugins%2Fguest-capabilities.html b/devdocs/vagrant/plugins%2Fguest-capabilities.html new file mode 100644 index 00000000..8dd11b82 --- /dev/null +++ b/devdocs/vagrant/plugins%2Fguest-capabilities.html @@ -0,0 +1,22 @@ +<h1 id="plugin-development-guest-capabilities"> Plugin Development: Guest Capabilities </h1> <p>This page documents how to add new capabilities for <a href="guests">guests</a> to Vagrant, allowing Vagrant to perform new actions on specific guest operating systems. Prior to reading this, you should be familiar with the <a href="development-basics">plugin development basics</a>.</p> <blockquote class="alert alert-warning"> <p><strong>Warning: Advanced Topic!</strong> Developing plugins is an advanced topic that only experienced Vagrant users who are reasonably comfortable with Ruby should approach.</p> </blockquote> +<p>Guest capabilities augment <a href="guests">guests</a> by attaching specific "capabilities" to the guest, which are actions that can be performed in the context of that guest operating system.</p> <p>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.</p> <h2 id="definition-component"> Definition Component </h2> <p>Within the context of a plugin definition, guest capabilities can be defined like so:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">guest_capability "ubuntu", "my_custom_capability" do + require_relative "cap/my_custom_capability" + Cap::MyCustomCapability +end +</pre></div> +<p>Guest capabilities are defined by calling the <code>guest_capability</code> 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.</p> <h2 id="implementation"> Implementation </h2> <p>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 <code>guest_capability</code> component, meaning that if it is an instance method, an instance should be returned.</p> <p>In general, class methods are used for capabilities. For example, here is the implementation for the capability above:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">module Cap + class MyCustomCapability + def self.my_custom_capability(machine) + # implementation + end + end +end +</pre></div> +<p>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.</p> <p>Some capabilities must also return values back to the caller, so be aware of that when implementing a capability.</p> <p>Capabilities always have access to communication channels such as SSH on the machine, and the machine can generally be assumed to be booted.</p> <h2 id="calling-capabilities"> Calling Capabilities </h2> <p>Since you have access to the machine in every capability, capabilities can also call <em>other</em> 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.</p> <p>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.</p> <p>Capabilities can be called like so:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">machine.guest.capability(:capability_name) +</pre></div> +<p>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.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/plugins/guest-capabilities.html" class="_attribution-link">https://www.vagrantup.com/docs/plugins/guest-capabilities.html</a> + </p> +</div> diff --git a/devdocs/vagrant/plugins%2Fguests.html b/devdocs/vagrant/plugins%2Fguests.html new file mode 100644 index 00000000..2aef797e --- /dev/null +++ b/devdocs/vagrant/plugins%2Fguests.html @@ -0,0 +1,23 @@ +<h1 id="plugin-development-guests"> Plugin Development: Guests </h1> <p>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 <a href="development-basics">plugin development basics</a>.</p> <blockquote class="alert alert-warning"> <p><strong>Warning: Advanced Topic!</strong> Developing plugins is an advanced topic that only experienced Vagrant users who are reasonably comfortable with Ruby should approach.</p> </blockquote> +<p>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.</p> <h2 id="definition-component"> Definition Component </h2> <p>Within the context of a plugin definition, new guests can be defined like so:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">guest "ubuntu" do + require_relative "guest" + Guest +end +</pre></div> +<p>Guests are defined with the <code>guest</code> 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 <code>Vagrant.plugin(2, :guest)</code> interface.</p> <h2 id="implementation"> Implementation </h2> <p>Implementations of guests subclass <code>Vagrant.plugin("2", "guest")</code>. Within this implementation, only the <code>detect?</code> method needs to be implemented.</p> <p>The <code>detect?</code> 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 <code>true</code> from <code>detect?</code>. Otherwise, return <code>false</code>.</p> <p>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:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">class MyGuest < Vagrant.plugin("2", "guest") + def detect?(machine) + machine.communicate.test("cat /etc/myos-release") + end +end +</pre></div> +<p>After detecting an OS, that OS is used for various <a href="guest-capabilities">guest capabilities</a> that may be required.</p> <h2 id="guest-inheritance"> Guest Inheritance </h2> <p>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.</p> <p>Inheritance is not done via standard Ruby class inheritance because Vagrant uses a custom <a href="guest-capabilities">capability-based</a> system. Vagrant handles inheritance dispatch for you.</p> <p>To subclass another guest, specify that guest's name as a second parameter in the guest definition:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">guest "ubuntu", "debian" do + require_relative "guest" + Guest +end +</pre></div> +<p>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.</p> <p>When detecting operating systems with <code>detect?</code>, 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 <code>detect?</code> method on "ubuntu" will be called before "debian."</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/plugins/guests.html" class="_attribution-link">https://www.vagrantup.com/docs/plugins/guests.html</a> + </p> +</div> diff --git a/devdocs/vagrant/plugins%2Fhost-capabilities.html b/devdocs/vagrant/plugins%2Fhost-capabilities.html new file mode 100644 index 00000000..c41d3660 --- /dev/null +++ b/devdocs/vagrant/plugins%2Fhost-capabilities.html @@ -0,0 +1,9 @@ +<h1 id="plugin-development-host-capabilities"> Plugin Development: Host Capabilities </h1> <p>This page documents how to add new capabilities for <a href="hosts">hosts</a> to Vagrant, allowing Vagrant to perform new actions on specific host operating systems. Prior to reading this, you should be familiar with the <a href="development-basics">plugin development basics</a>.</p> <blockquote class="alert alert-warning"> <p><strong>Warning: Advanced Topic!</strong> Developing plugins is an advanced topic that only experienced Vagrant users who are reasonably comfortable with Ruby should approach.</p> </blockquote> +<p>Host capabilities augment <a href="hosts">hosts</a> by attaching specific "capabilities" to the host, which are actions that can be performed in the context of that host operating system.</p> <p>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.</p> <h2 id="definition-and-implementation"> Definition and Implementation </h2> <p>The definition and implementation of host capabilities is identical to <a href="guest-capabilities">guest capabilities</a>.</p> <p>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 <code>Vagrant::Environment</code> as their first argument.</p> <p>Access to the environment allows host capabilities to access global state, specific machines, and also allows them to call other host capabilities.</p> <h2 id="calling-capabilities"> Calling Capabilities </h2> <p>Since you have access to the environment in every capability, capabilities can also call <em>other</em> 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.</p> <p>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.</p> <p>Capabilities can be called like so:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">environment.host.capability(:capability_name) +</pre></div> +<p>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.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/plugins/host-capabilities.html" class="_attribution-link">https://www.vagrantup.com/docs/plugins/host-capabilities.html</a> + </p> +</div> diff --git a/devdocs/vagrant/plugins%2Fhosts.html b/devdocs/vagrant/plugins%2Fhosts.html new file mode 100644 index 00000000..c5fd5344 --- /dev/null +++ b/devdocs/vagrant/plugins%2Fhosts.html @@ -0,0 +1,23 @@ +<h1 id="plugin-development-hosts"> Plugin Development: Hosts </h1> <p>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 <a href="development-basics">plugin development basics</a>.</p> <blockquote class="alert alert-warning"> <p><strong>Warning: Advanced Topic!</strong> Developing plugins is an advanced topic that only experienced Vagrant users who are reasonably comfortable with Ruby should approach.</p> </blockquote> +<p>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 <a href="host-capabilities">host capabilities</a> to perform these host OS-specific operations.</p> <h2 id="definition-component"> Definition Component </h2> <p>Within the context of a plugin definition, new hosts can be defined like so:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">host "ubuntu" do + require_relative "host" + Host +end +</pre></div> +<p>Hosts are defined with the <code>host</code> 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 <code>Vagrant.plugin(2, :host)</code> interface.</p> <h2 id="implementation"> Implementation </h2> <p>Implementations of hosts subclass <code>Vagrant.plugin("2", "host")</code>. Within this implementation, only the <code>detect?</code> method needs to be implemented.</p> <p>The <code>detect?</code> 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 <code>true</code> from <code>detect?</code>. Otherwise, return <code>false</code>.</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">class MyHost < Vagrant.plugin("2", "host") + def detect?(environment) + File.file?("/etc/arch-release") + end +end +</pre></div> +<p>After detecting an OS, that OS is used for various <a href="host-capabilities">host capabilities</a> that may be required.</p> <h2 id="host-inheritance"> Host Inheritance </h2> <p>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.</p> <p>Inheritance is not done via standard Ruby class inheritance because Vagrant uses a custom <a href="host-capabilities">capability-based</a> system. Vagrant handles inheritance dispatch for you.</p> <p>To subclass another host, specify that host's name as a second parameter in the host definition:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">host "ubuntu", "debian" do + require_relative "host" + Host +end +</pre></div> +<p>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.</p> <p>When detecting operating systems with <code>detect?</code>, 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 <code>detect?</code> method on "ubuntu" will be called before "debian."</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/plugins/hosts.html" class="_attribution-link">https://www.vagrantup.com/docs/plugins/hosts.html</a> + </p> +</div> diff --git a/devdocs/vagrant/plugins%2Findex.html b/devdocs/vagrant/plugins%2Findex.html new file mode 100644 index 00000000..eb8b1e6d --- /dev/null +++ b/devdocs/vagrant/plugins%2Findex.html @@ -0,0 +1,6 @@ +<h1 id="plugins"> Plugins </h1> <p>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 <em>plugins</em>.</p> <p>Plugins are powerful, first-class citizens that extend Vagrant using a well-documented, stable API that can withstand major version upgrades.</p> <p>In fact, most of the core of Vagrant is <a href="https://github.com/hashicorp/vagrant/tree/master/plugins">implemented using plugins</a>. Since Vagrant <a href="https://en.wikipedia.org/wiki/Eating_your_own_dog_food">dogfoods</a> its own plugin API, you can be confident that the interface is stable and well supported.</p> <p>Use the navigation on the left below the "Plugins" section to learn more about how to use and build your own plugins.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/plugins/" class="_attribution-link">https://www.vagrantup.com/docs/plugins/</a> + </p> +</div> diff --git a/devdocs/vagrant/plugins%2Fpackaging.html b/devdocs/vagrant/plugins%2Fpackaging.html new file mode 100644 index 00000000..ff193fdb --- /dev/null +++ b/devdocs/vagrant/plugins%2Fpackaging.html @@ -0,0 +1,23 @@ +<h1 id="plugin-development-packaging-amp-distribution"> Plugin Development: Packaging & Distribution </h1> <p>This page documents how to organize the file structure of your plugin and distribute it so that it is installable using <a href="usage">standard installation methods</a>. Prior to reading this, you should be familiar with the <a href="development-basics">plugin development basics</a>.</p> <blockquote class="alert alert-warning"> <p><strong>Warning: Advanced Topic!</strong> Developing plugins is an advanced topic that only experienced Vagrant users who are reasonably comfortable with Ruby should approach.</p> </blockquote> +<h2 id="example-plugin"> Example Plugin </h2> <p>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 <a href="https://github.com/mitchellh/vagrant-aws">vagrant-aws</a>.</p> <p>By using <a href="http://bundler.io">Bundler</a> and Rake, building a new vagrant-aws package is easy. By simply calling <code>rake package</code>, a <code>gem</code> file is dropped into the directory. By calling <code>rake release</code>, the gem is built and it is uploaded to the central <a href="https://rubygems.org">RubyGems</a> repository so that it can be installed using <code>vagrant plugin install</code>.</p> <p>Your plugin can and should be this easy, too, since you basically get this for free by using Bundler.</p> <h2 id="setting-up-your-project"> Setting Up Your Project </h2> <p>To setup your project, run <code>bundle gem vagrant-my-plugin</code>. This will create a <code>vagrant-my-plugin</code> directory that has the initial layout to be a RubyGem.</p> <p>You should modify the <code>vagrant-my-plugin.gemspec</code> file to add any dependencies and change any metadata. View the <a href="https://github.com/mitchellh/vagrant-aws/blob/master/vagrant-aws.gemspec">vagrant-aws.gemspec</a> for a good example.</p> <blockquote class="alert alert-warning"> +<p><strong>Do not depend on Vagrant</strong> 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.</p> </blockquote> +<p>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:</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<p>This Gemfile gets "vagrant" for development. This allows you to <code>bundle exec vagrant</code> to run Vagrant with your plugin already loaded, so that you can test it manually that way.</p> <p>The only thing about this Gemfile that may stand out as odd is the "plugins" group and putting your plugin in that group. Because <code>vagrant plugin</code> 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.</p> <p>Next, create a <code>Rakefile</code> that has at the very least, the following contents:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">require "rubygems" +require "bundler/setup" +Bundler::GemHelper.install_tasks +</pre></div> +<p>If you run <code>rake -T</code> now, which lists all the available rake tasks, you should see that you have the <code>package</code> and <code>release</code> tasks. You can now develop your plugin and build it!</p> <p>You can view the <a href="https://github.com/mitchellh/vagrant-aws/blob/master/Rakefile">vagrant-aws Rakefile</a> for a more comprehensive example that includes testing.</p> <h2 id="testing-your-plugin"> Testing Your Plugin </h2> <p>To manually test your plugin during development, use <code>bundle exec vagrant</code> to execute Vagrant with your plugin loaded (thanks to the Gemfile setup we did earlier).</p> <p>For automated testing, the <a href="https://github.com/hashicorp/vagrant-spec">vagrant-spec</a> 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.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/plugins/packaging.html" class="_attribution-link">https://www.vagrantup.com/docs/plugins/packaging.html</a> + </p> +</div> diff --git a/devdocs/vagrant/plugins%2Fproviders.html b/devdocs/vagrant/plugins%2Fproviders.html new file mode 100644 index 00000000..ff311ae9 --- /dev/null +++ b/devdocs/vagrant/plugins%2Fproviders.html @@ -0,0 +1,30 @@ +<h1 id="plugin-development-providers"> Plugin Development: Providers </h1> <p>This page documents how to add support for new <a href="../providers/index">providers</a> 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 <a href="development-basics">plugin development basics</a>.</p> <p>Prior to developing a provider you should also be familiar with how <a href="../providers/index">providers work</a> from a user standpoint.</p> <blockquote class="alert alert-warning"> <p><strong>Warning: Advanced Topic!</strong> Developing plugins is an advanced topic that only experienced Vagrant users who are reasonably comfortable with Ruby should approach.</p> </blockquote> +<h2 id="example-provider-aws"> Example Provider: AWS </h2> <p>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 <a href="https://github.com/mitchellh/vagrant-aws">vagrant-aws</a> plugin, which implements an AWS provider. The plugin is a good example of how to structure, test, and implement your plugin.</p> <h2 id="definition-component"> Definition Component </h2> <p>Within the context of a plugin definition, new providers are defined like so:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">provider "my_cloud" do + require_relative "provider" + Provider +end +</pre></div> +<p>Providers are defined with the <code>provider</code> method, which takes a single argument specifying the name of the provider. This is the name that is used with <code>vagrant up</code> to specify the provider. So in the case above, our provider would be used by calling <code>vagrant up --provider=my_cloud</code>.</p> <p>The block argument then lazily loads and returns a class that implements the <code>Vagrant.plugin(2, :provider)</code> interface, which is covered next.</p> <h2 id="provider-class"> Provider Class </h2> <p>The provider class should subclass and implement <code>Vagrant.plugin(2, :provider)</code> which is an upgrade-safe way to let Vagrant return the proper parent class.</p> <p>This class and the methods that need to be implemented are <a href="https://github.com/hashicorp/vagrant/blob/master/lib/vagrant/plugin/v2/provider.rb">very well documented</a>. The documentation done on the class in the comments should be enough to understand what needs to be done.</p> <p>Viewing the <a href="https://github.com/mitchellh/vagrant-aws/blob/master/lib/vagrant-aws/provider.rb">AWS provider class</a> as well as the <a href="https://github.com/mitchellh/vagrant-aws">overall structure of the plugin</a> is recommended as a strong getting started point.</p> <p>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.</p> <h2 id="box-format"> Box Format </h2> <p>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 <a href="../boxes/format">box file format</a>.</p> <p>The only requirement for your box format is that the <code>metadata.json</code> file have a <code>provider</code> key which matches the name of your provider you chose above.</p> <p>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.</p> <p>As an example of a couple box formats that are actually in use:</p> <ul> <li> +<p>The <code>virtualbox</code> box format is just a flat directory of the contents of a <code>VBoxManage export</code> command.</p> </li> <li> +<p>The <code>vmware_fusion</code> box format is just a flat directory of the contents of a <code>vmwarevm</code> folder, but only including the bare essential files for VMware to function.</p> </li> <li> +<p>The <code>aws</code> box format is just a Vagrantfile defaulting some configuration. You can see an <a href="https://github.com/mitchellh/vagrant-aws/tree/master/example_box">example aws box unpacked here</a>.</p> </li> </ul> <p>Before anything with your provider is even written, you can verify your box format works by doing <code>vagrant box add</code> with it. When you do a <code>vagrant box list</code> you can see what boxes for what providers are installed.</p> <p>You do <em>not need</em> the provider plugin installed to add a box for that provider.</p> <h2 id="actions"> Actions </h2> <p>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.</p> <p>Actions are built on top of the concept of <a href="https://github.com/mitchellh/middleware">middleware</a>, which allow providers to execute multiple distinct steps, have error recovery mechanics, as well as before/after behaviors, and much more.</p> <p>Vagrant core requests specific actions from your provider through the <code>action</code> 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.</p> <p>Take a look at how the VirtualBox provider <a href="https://github.com/hashicorp/vagrant/blob/master/plugins/providers/virtualbox/action.rb#L287">uses actions to build up complicated multi-step processes</a>. The AWS provider <a href="https://github.com/mitchellh/vagrant-aws/blob/master/lib/vagrant-aws/action.rb">uses a similar process</a>.</p> <h2 id="built-in-middleware"> Built-in Middleware </h2> <p>To assist with common tasks, Vagrant ships with a set of <a href="https://github.com/hashicorp/vagrant/tree/master/lib/vagrant/action/builtin">built-in middleware</a>. 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.</p> <p>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.</p> <h2 id="persisting-state"> Persisting State </h2> <p>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.</p> <p>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.</p> <p>The VMware provider actually copies the entire virtual machine into this state directory, complete with virtual disk drives and everything.</p> <p>The directory is available from the <code>data_dir</code> attribute of the <code>Machine</code> instance given to initialize your provider. Within middleware actions, the machine is always available via the <code>:machine</code> key on the environment. The <code>data_dir</code> attribute is a Ruby <a href="http://www.ruby-doc.org/stdlib-1.9.3/libdoc/pathname/rdoc/Pathname.html">Pathname</a> object.</p> <p>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.</p> <h2 id="configuration"> Configuration </h2> <p>Vagrant supports <a href="../providers/configuration">provider-specific configuration</a>, 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.</p> <p>Provider-specific configuration is a special case of a normal <a href="configuration">configuration plugin</a>. When defining the configuration component, name the configuration the same as the provider, and as a second parameter, specify <code>:provider</code>, like so:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config("my_cloud", :provider) do + require_relative "config" + Config +end +</pre></div> +<p>As long as the name matches your provider, and the second <code>:provider</code> parameter is given, Vagrant will automatically expose this as provider-specific configuration for your provider. Users can now do the following in their Vagrantfiles:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.provider :my_cloud do |config| + # Your specific configuration! +end +</pre></div> +<p>The configuration class returned from the <code>config</code> component in the plugin is the same as any other <a href="configuration">configuration plugin</a>, so read that page for more information. Vagrant automatically handles configuration validation and such just like any other configuration piece.</p> <p>The provider-specific configuration is available on the machine object via the <code>provider_config</code> attribute. So within actions or your provider class, you can access the config via <code>machine.provider_config</code>.</p> <blockquote class="alert alert-info"> <p><strong>Best practice:</strong> Your provider should <em>not require</em> provider-specific configuration to function, if possible. Vagrant practices a strong <a href="https://en.wikipedia.org/wiki/Convention_over_configuration">convention over configuration</a> philosophy. When a user installs your provider, they should ideally be able to <code>vagrant up --provider=your_provider</code> and have it just work.</p> </blockquote> +<h2 id="parallelization"> Parallelization </h2> <p>Vagrant supports parallelizing some actions, such as <code>vagrant up</code>, if the provider explicitly supports it. By default, Vagrant will not parallelize a provider.</p> <p>When parallelization is enabled, multiple <a href="#actions">actions</a> 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.</p> <p>Providers can explicitly enable parallelization by setting the <code>parallel</code> option on the provider component:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">provider("my_cloud", parallel: true) do + require_relative "provider" + Provider +end +</pre></div> +<p>That is the only change that is needed to enable parallelization.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/plugins/providers.html" class="_attribution-link">https://www.vagrantup.com/docs/plugins/providers.html</a> + </p> +</div> diff --git a/devdocs/vagrant/plugins%2Fprovisioners.html b/devdocs/vagrant/plugins%2Fprovisioners.html new file mode 100644 index 00000000..e1deb123 --- /dev/null +++ b/devdocs/vagrant/plugins%2Fprovisioners.html @@ -0,0 +1,12 @@ +<h1 id="plugin-development-provisioners"> Plugin Development: Provisioners </h1> <p>This page documents how to add new <a href="../provisioning/index">provisioners</a> 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 <a href="development-basics">plugin development basics</a>.</p> <blockquote class="alert alert-warning"> <p><strong>Warning: Advanced Topic!</strong> Developing plugins is an advanced topic that only experienced Vagrant users who are reasonably comfortable with Ruby should approach.</p> </blockquote> +<h2 id="definition-component"> Definition Component </h2> <p>Within the context of a plugin definition, new provisioners can be defined like so:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">provisioner "custom" do + require_relative "provisioner" + Provisioner +end +</pre></div> +<p>Provisioners are defined with the <code>provisioner</code> method, which takes a single argument specifying the name of the provisioner. This is the name that used with <code>config.vm.provision</code> when configuring and enabling the provisioner. So in the case above, the provisioner would be enabled using <code>config.vm.provision :custom</code>.</p> <p>The block argument then lazily loads and returns a class that implements the <code>Vagrant.plugin(2, :provisioner)</code> interface, which is covered next.</p> <h2 id="provisioner-class"> Provisioner Class </h2> <p>The provisioner class should subclass and implement <code>Vagrant.plugin(2, :provisioner)</code> which is an upgrade-safe way to let Vagrant return the proper parent class for provisioners.</p> <p>This class and the methods that need to be implemented are <a href="https://github.com/hashicorp/vagrant/blob/master/lib/vagrant/plugin/v2/provisioner.rb">very well documented</a>. The documentation on the class in the comments should be enough to understand what needs to be done.</p> <p>There are two main methods that need to be implemented: the <code>configure</code> method and the <code>provision</code> method.</p> <p>The <code>configure</code> 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 <a href="https://github.com/hashicorp/vagrant/blob/master/plugins/provisioners/chef/provisioner/chef_solo.rb#L24">Chef solo provisioner</a> uses this to define shared folders.</p> <p>The <code>provision</code> 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.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/plugins/provisioners.html" class="_attribution-link">https://www.vagrantup.com/docs/plugins/provisioners.html</a> + </p> +</div> diff --git a/devdocs/vagrant/plugins%2Fusage.html b/devdocs/vagrant/plugins%2Fusage.html new file mode 100644 index 00000000..c14b42d8 --- /dev/null +++ b/devdocs/vagrant/plugins%2Fusage.html @@ -0,0 +1,15 @@ +<h1 id="plugin-usage"> Plugin Usage </h1> <p>Installing a Vagrant plugin is easy, and should not take more than a few seconds.</p> <p>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.</p> <blockquote class="alert alert-warning"> <p><strong>Warning!</strong> 3rd party plugins can introduce instabilities into Vagrant due to the nature of them being written by non-core users.</p> </blockquote> +<h2 id="installation"> Installation </h2> <p>Plugins are installed using <code>vagrant plugin install</code>:</p> <div class="highlight"><pre class="highlight shell" data-language="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 +</pre></div> +<p>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.</p> <h2 id="usage"> Usage </h2> <p>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 <code>vagrant</code>, provisioners should be available via <code>config.vm.provision</code>, etc.</p> <p><strong>Note:</strong> In the future, the <code>vagrant plugin</code> command will include a subcommand that will document the components that each plugin installs.</p> <h2 id="updating"> Updating </h2> <p>Plugins can be updated by running <code>vagrant plugin update</code>. This will update every installed plugin to the latest version. You can update a specific plugin by calling <code>vagrant plugin update NAME</code>. Vagrant will output what plugins were updated and to what version.</p> <p>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.</p> <h2 id="uninstallation"> Uninstallation </h2> <p>Uninstalling a plugin is as easy as installing it. Just use the <code>vagrant plugin uninstall</code> command and the plugin will be removed. Example:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ vagrant plugin uninstall my-plugin +</pre></div> +<h2 id="listing-plugins"> Listing Plugins </h2> <p>To view what plugins are installed into your Vagrant environment at any time, use the <code>vagrant plugin list</code> command. This will list the plugins that are installed along with their version.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/plugins/usage.html" class="_attribution-link">https://www.vagrantup.com/docs/plugins/usage.html</a> + </p> +</div> diff --git a/devdocs/vagrant/providers%2Fbasic_usage.html b/devdocs/vagrant/providers%2Fbasic_usage.html new file mode 100644 index 00000000..4793dfe7 --- /dev/null +++ b/devdocs/vagrant/providers%2Fbasic_usage.html @@ -0,0 +1,27 @@ +<h1 id="basic-provider-usage"> Basic Provider Usage </h1> <h2 id="boxes"> Boxes </h2> <p>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 "precise64" box.</p> <p>Installing boxes has not changed at all:</p> <div class="highlight"><pre class="highlight plaintext">$ vagrant box add hashicorp/precise64 +</pre></div> +<p>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.</p> <div class="highlight"><pre class="highlight plaintext">$ vagrant box list +precise64 (virtualbox) +precise64 (vmware_fusion) +</pre></div> +<h2 id="vagrant-up"> Vagrant Up </h2> <p>Once a provider is installed, you can use it by calling <code>vagrant up</code> with the <code>--provider</code> flag. This will force Vagrant to use that specific provider. No other configuration is necessary!</p> <p>In normal day-to-day usage, the <code>--provider</code> flag is not necessary since Vagrant can usually pick the right provider for you. More details on how it does this is below.</p> <div class="highlight"><pre class="highlight plaintext">$ vagrant up --provider=vmware_fusion +</pre></div> +<p>If you specified a <code>--provider</code> flag, you only need to do this for the <code>up</code> command. Once a machine is up and running, Vagrant is able to see what provider is backing a running machine, so commands such as <code>destroy</code>, <code>suspend</code>, etc. do not need to be told what provider to use.</p> <blockquote class="alert alert-info"> <p>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 <em>same machine</em> with both VirtualBox and VMware Fusion. This is a limitation that will be removed in a future version of Vagrant.</p> </blockquote> +<h2 id="default-provider"> Default Provider </h2> <p>As mentioned earlier, you typically do not need to specify <code>--provider</code> <em>ever</em>. Vagrant is smart enough about being able to detect the provider you want for a given environment.</p> <p>Vagrant attempts to find the default provider in the following order:</p> <ol> <li> +<p>The <code>--provider</code> flag on a <code>vagrant up</code> is chosen above all else, if it is present.</p> </li> <li> +<p>If the <code>VAGRANT_DEFAULT_PROVIDER</code> environmental variable is set, it takes next priority and will be the provider chosen.</p> </li> <li> +<p>Vagrant will go through all of the <code>config.vm.provider</code> 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.</p> </li> <li> +<p>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.</p> </li> <li> +<p>If Vagrant still has not found any usable providers, it will error.</p> </li> </ol> <p>Using this method, there are very few cases that Vagrant does not find the correct provider for you. This also allows each <a href="../vagrantfile/index">Vagrantfile</a> to define what providers the development environment is made for by ordering provider configurations.</p> <p>A trick is to use <code>config.vm.provider</code> with no configuration at the top of your Vagrantfile to define the order of providers you prefer to support:</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/providers/basic_usage.html" class="_attribution-link">https://www.vagrantup.com/docs/providers/basic_usage.html</a> + </p> +</div> diff --git a/devdocs/vagrant/providers%2Fconfiguration.html b/devdocs/vagrant/providers%2Fconfiguration.html new file mode 100644 index 00000000..cfdc3f4c --- /dev/null +++ b/devdocs/vagrant/providers%2Fconfiguration.html @@ -0,0 +1,22 @@ +<h1 id="configuration"> Configuration </h1> <p>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.</p> <p>This provider-specific configuration is done within the Vagrantfile in a way that is portable, easy to use, and easy to understand.</p> <h2 id="portability"> Portability </h2> <p>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.</p> <p>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.</p> <h2 id="provider-configuration"> Provider Configuration </h2> <p>Configuring a specific provider looks like this:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + # ... + + config.vm.provider "virtualbox" do |vb| + vb.customize ["modifyvm", :id, "--cpuexecutioncap", "50"] + end +end +</pre></div> +<p>Multiple <code>config.vm.provider</code> blocks can exist to configure multiple providers.</p> <p>The configuration format should look very similar to how provisioners are configured. The <code>config.vm.provider</code> 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.</p> <p>This inner configuration differs among providers, so please read the documentation for your provider of choice to see available configuration options.</p> <p>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.</p> <h2 id="overriding-configuration"> Overriding Configuration </h2> <p>Providers can also override non-provider specific configuration, such as <code>config.vm.box</code> and any other Vagrant configuration. This is done by specifying a second argument to <code>config.vm.provider</code>. This argument is just like the normal <code>config</code>, so set any settings you want, and they will be overridden only for that provider.</p> <p>Example:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.box = "precise64" + + config.vm.provider "vmware_fusion" do |v, override| + override.vm.box = "precise64_fusion" + end +end +</pre></div> +<p>In the above case, Vagrant will use the "precise64" box by default, but will use "precise64_fusion" if the VMware Fusion provider is used.</p> <blockquote class="alert alert-info"> <p><strong>The Vagrant Way:</strong> 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.</p> </blockquote><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/providers/configuration.html" class="_attribution-link">https://www.vagrantup.com/docs/providers/configuration.html</a> + </p> +</div> diff --git a/devdocs/vagrant/providers%2Fcustom.html b/devdocs/vagrant/providers%2Fcustom.html new file mode 100644 index 00000000..a123cfdc --- /dev/null +++ b/devdocs/vagrant/providers%2Fcustom.html @@ -0,0 +1,6 @@ +<h1 id="custom-provider"> Custom Provider </h1> <p>To learn how to make your own custom Vagrant providers, read the Vagrant plugin development guide on <a href="../plugins/providers">creating custom providers</a>.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/providers/custom.html" class="_attribution-link">https://www.vagrantup.com/docs/providers/custom.html</a> + </p> +</div> diff --git a/devdocs/vagrant/providers%2Fdefault.html b/devdocs/vagrant/providers%2Fdefault.html new file mode 100644 index 00000000..85cbbbcc --- /dev/null +++ b/devdocs/vagrant/providers%2Fdefault.html @@ -0,0 +1,6 @@ +<h1 id="default-provider"> Default Provider </h1> <p>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.</p> <p>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 <code>VAGRANT_DEFAULT_PROVIDER</code> environmental variable.</p> <p>Just set <code>VAGRANT_DEFAULT_PROVIDER</code> 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 <code>vmware_fusion</code> and it will be your default.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/providers/default.html" class="_attribution-link">https://www.vagrantup.com/docs/providers/default.html</a> + </p> +</div> diff --git a/devdocs/vagrant/providers%2Findex.html b/devdocs/vagrant/providers%2Findex.html new file mode 100644 index 00000000..1931f338 --- /dev/null +++ b/devdocs/vagrant/providers%2Findex.html @@ -0,0 +1,6 @@ +<h1 id="providers"> Providers </h1> <p>While Vagrant ships out of the box with support for <a href="https://www.virtualbox.org">VirtualBox</a>, <a href="https://www.microsoft.com/hyper-v">Hyper-V</a>, and <a href="https://www.docker.io">Docker</a>, Vagrant has the ability to manage other types of machines as well. This is done by using other <em>providers</em> with Vagrant.</p> <p>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, <a href="https://www.vmware.com">VMware</a> providers are recommended since they're well supported and generally more stable and performant than VirtualBox.</p> <p>Before you can use another provider, you must install it. Installation of other providers is done via the Vagrant plugin system.</p> <p>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.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/providers/" class="_attribution-link">https://www.vagrantup.com/docs/providers/</a> + </p> +</div> diff --git a/devdocs/vagrant/providers%2Finstallation.html b/devdocs/vagrant/providers%2Finstallation.html new file mode 100644 index 00000000..b183c4e6 --- /dev/null +++ b/devdocs/vagrant/providers%2Finstallation.html @@ -0,0 +1,6 @@ +<h1 id="provider-installation"> Provider Installation </h1> <p>Providers are distributed as Vagrant plugins, and are therefore installed using <a href="../plugins/usage">standard plugin installation steps</a>. After installing a plugin which contains a provider, the provider should immediately be available.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/providers/installation.html" class="_attribution-link">https://www.vagrantup.com/docs/providers/installation.html</a> + </p> +</div> diff --git a/devdocs/vagrant/provisioning%2Fansible.html b/devdocs/vagrant/provisioning%2Fansible.html new file mode 100644 index 00000000..70895a6b --- /dev/null +++ b/devdocs/vagrant/provisioning%2Fansible.html @@ -0,0 +1,64 @@ +<h1 id="ansible-provisioner"> Ansible Provisioner </h1> <p><strong>Provisioner name: <code>ansible</code></strong></p> <p>The Vagrant Ansible provisioner allows you to provision the guest using <a href="http://ansible.com">Ansible</a> playbooks by executing <strong><code>ansible-playbook</code> from the Vagrant host</strong>.</p> <blockquote class="alert alert-warning"> <p><strong>Warning:</strong> If you are not familiar with Ansible and Vagrant already, I recommend starting with the <a href="shell">shell provisioner</a>. However, if you are comfortable with Vagrant already, Vagrant is a great way to learn Ansible.</p> </blockquote> +<h2 id="setup-requirements"> Setup Requirements </h2> <ul> <li> +<p><strong><a href="https://docs.ansible.com/intro_installation.html#installing-the-control-machine">Install Ansible</a> on your Vagrant host</strong>.</p> </li> <li> +<p>Your Vagrant host should ideally provide a recent version of OpenSSH that <a href="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">supports ControlPersist</a>.</p> </li> </ul> <p>If installing Ansible directly on the Vagrant host is not an option in your development environment, you might be looking for the <a href="ansible_local">Ansible Local provisioner</a> alternative.</p> <h2 id="usage"> Usage </h2> <p>This page only documents the specific parts of the <code>ansible</code> (remote) provisioner. General Ansible concepts like Playbook or Inventory are shortly explained in the <a href="ansible_intro">introduction to Ansible and Vagrant</a>.</p> <h3 id="simplest-configuration"> Simplest Configuration </h3> <p>To run Ansible against your Vagrant guest, the basic <code>Vagrantfile</code> configuration looks like:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + + # + # Run Ansible from the Vagrant Host + # + config.vm.provision "ansible" do |ansible| + ansible.playbook = "playbook.yml" + end + +end +</pre></div> +<h2 id="options"> Options </h2> <p>This section lists the <em>specific</em> options for the Ansible (remote) provisioner. In addition to the options listed below, this provisioner supports the <a href="ansible_common"><strong>common options</strong> for both Ansible provisioners</a>.</p> <ul> <li> +<p><a href="#ask_become_pass"><code>ask_become_pass</code></a> (boolean) - require Ansible to <a href="https://docs.ansible.com/intro_getting_started.html#remote-connection-information">prompt for a password</a> when switching to another user with the <a href="http://docs.ansible.com/ansible/become.html">become/sudo mechanism</a>.</p> <p>The default value is <code>false</code>.</p> </li> <li> +<p><a href="#ask_sudo_pass"><code>ask_sudo_pass</code></a> (boolean) - Backwards compatible alias for the <a href="#ask_become_pass">ask_become_pass</a> option.</p> <blockquote class="alert alert-warning"> <p><strong>Deprecation:</strong> The <code>ask_sudo_pass</code> option is deprecated and will be removed in a future release. Please use the <a href="#ask_become_pass"><strong><code>ask_become_pass</code></strong></a> option instead.</p> </blockquote> +</li> <li> +<p><a href="#ask_vault_pass"><code>ask_vault_pass</code></a> (boolean) - require Ansible to <a href="https://docs.ansible.com/playbooks_vault.html#vault">prompt for a vault password</a>.</p> <p>The default value is <code>false</code>.</p> </li> <li> +<p><a href="#force_remote_user"><code>force_remote_user</code></a> (boolean) - require Vagrant to set the <code>ansible_ssh_user</code> setting in the generated inventory, or as an extra variable when a static inventory is used. All the Ansible <code>remote_user</code> parameters will then be overridden by the value of <code>config.ssh.username</code> of the <a href="../vagrantfile/ssh_settings">Vagrant SSH Settings</a>.</p> <p>If this option is set to <code>false</code> Vagrant will set the Vagrant SSH username as a default Ansible remote user, but <code>remote_user</code> parameters of your Ansible plays or tasks will still be taken into account and thus override the Vagrant configuration.</p> <p>The default value is <code>true</code>.</p> <blockquote class="alert alert-info"> <p><strong>Compatibility Note:</strong> This option was introduced in Vagrant 1.8.0. Previous Vagrant versions behave like if this option was set to <code>false</code>.</p> </blockquote> +</li> <li> +<p><a href="#host_key_checking"><code>host_key_checking</code></a> (boolean) - require Ansible to <a href="https://docs.ansible.com/intro_getting_started.html#host-key-checking">enable SSH host key checking</a>.</p> <p>The default value is <code>false</code>.</p> </li> <li> +<p><a href="#raw_ssh_args"><code>raw_ssh_args</code></a> (array of strings) - require Ansible to apply a list of OpenSSH client options.</p> <p>Example: <code>['-o ControlMaster=no']</code>.</p> <p>It is an <em>unsafe wildcard</em> that can be used to pass additional SSH settings to Ansible via <code>ANSIBLE_SSH_ARGS</code> environment variable, overriding any other SSH arguments (e.g. defined in an <a href="https://docs.ansible.com/intro_configuration.html#ssh-args"><code>ansible.cfg</code> configuration file</a>).</p> </li> </ul> <h2 id="tips-and-tricks"> Tips and Tricks </h2> <h3 id="ansible-parallel-execution"> Ansible Parallel Execution </h3> <p>Vagrant is designed to provision <a href="../multi-machine">multi-machine environments</a> in sequence, but the following configuration pattern can be used to take advantage of Ansible parallelism:</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<blockquote class="alert alert-info"> <p><strong>Tip:</strong> If you apply this parallel provisioning pattern with a static Ansible inventory, you will have to organize the things so that <a href="https://github.com/hashicorp/vagrant/pull/5765#issuecomment-120247738">all the relevant private keys are provided to the <code>ansible-playbook</code> command</a>. The same kind of considerations applies if you are using multiple private keys for a same machine (see <a href="../vagrantfile/ssh_settings"><code>config.ssh.private_key_path</code> SSH setting</a>).</p> </blockquote> +<h3 id="force-paramiko-connection-mode"> Force Paramiko Connection Mode </h3> <p>The Ansible provisioner is implemented with native OpenSSH support in mind, and there is no official support for <a href="https://github.com/paramiko/paramiko/">paramiko</a> (A native Python SSHv2 protocol library).</p> <p>If you really need to use this connection mode though, it is possible to enable paramiko as illustrated in the following configuration examples:</p> <p>With auto-generated inventory:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">ansible.raw_arguments = ["--connection=paramiko"] +</pre></div> +<p>With a custom inventory, the private key must be specified (e.g. via an <code>ansible.cfg</code> configuration file, <code>--private-key</code> argument, or as part of your inventory file):</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">ansible.inventory_path = "./my-inventory" +ansible.raw_arguments = [ + "--connection=paramiko", + "--private-key=/home/.../.vagrant/machines/.../private_key" +] +</pre></div><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/provisioning/ansible.html" class="_attribution-link">https://www.vagrantup.com/docs/provisioning/ansible.html</a> + </p> +</div> diff --git a/devdocs/vagrant/provisioning%2Fansible_common.html b/devdocs/vagrant/provisioning%2Fansible_common.html new file mode 100644 index 00000000..70d86df8 --- /dev/null +++ b/devdocs/vagrant/provisioning%2Fansible_common.html @@ -0,0 +1,72 @@ +<h1 id="shared-ansible-options"> Shared Ansible Options </h1> <p>The following options are available to both Vagrant Ansible provisioners:</p> <ul> <li> +<a href="ansible"><code>ansible</code></a> </li> <li> +<a href="ansible_local"><code>ansible_local</code></a> </li> </ul> <p>These options get passed to the <code>ansible-playbook</code> command that ships with Ansible, either via command line arguments or environment variables, depending on Ansible own capabilities.</p> <p>Some of these options are for advanced usage only and should not be used unless you understand their purpose.</p> <ul> <li> +<p><a href="#become"><code>become</code></a> (boolean) - Perform all the Ansible playbook tasks <a href="http://docs.ansible.com/ansible/become.html">as another user</a>, different from the user used to log into the guest system.</p> <p>The default value is <code>false</code>.</p> </li> <li> +<p><a href="#become_user"><code>become_user</code></a> (string) - Set the default username to be used by the Ansible <code>become</code> <a href="http://docs.ansible.com/ansible/become.html">privilege escalation</a> mechanism.</p> <p>By default this option is not set, and the Ansible default value (<code>root</code>) will be used.</p> </li> <li> +<p><a href="#compatibility_mode"><code>compatibility_mode</code></a> (string) - Set the <strong>minimal</strong> version of Ansible to be supported. Vagrant will only use parameters that are compatible with the given version.</p> <p>Possible values:</p> <ul> <li> +<a href="#quot-auto-quot-"><code>"auto"</code></a> <em>(Vagrant will automatically select the optimal compatibility mode by checking the Ansible version currently available)</em> </li> <li> +<a href="#quot-1-8-quot-"><code>"1.8"</code></a> <em>(Ansible versions prior to 1.8 should mostly work well, but some options might not be supported)</em> </li> <li> +<a href="#quot-2-0-quot-"><code>"2.0"</code></a> <em>(The generated Ansible inventory will be incompatible with Ansible 1.x)</em> </li> </ul> <p>By default this option is set to <code>"auto"</code>. If Vagrant is not able to detect any supported Ansible version, it will fall back on the compatibility mode <code>"1.8"</code> with a warning.</p> <p>Vagrant will error if the specified compatibility mode is incompatible with the current Ansible version.</p> <blockquote class="alert alert-warning"> <p><strong>Attention:</strong> Vagrant doesn't perform any validation between the <code>compatibility_mode</code> value and the value of the <a href="#version"><code>version</code></a> option.</p> </blockquote> +<blockquote class="alert alert-info"> <p><strong>Compatibility Note:</strong> This option was introduced in Vagrant 2.0. The behavior of previous Vagrant versions can be simulated by setting the <code>compatibility_mode</code> to <code>"1.8"</code>.</p> </blockquote> +</li> <li> +<p><a href="#config_file"><code>config_file</code></a> (string) - The path to an <a href="https://docs.ansible.com/intro_configuration.html">Ansible Configuration file</a>.</p> <p>By default, this option is not set, and Ansible will <a href="ansible_intro#ANSIBLE_CONFIG">search for a possible configuration file in some default locations</a>.</p> </li> <li> +<p><a href="#extra_vars"><code>extra_vars</code></a> (string or hash) - Pass additional variables (with highest priority) to the playbook.</p> <p>This parameter can be a path to a JSON or YAML file, or a hash.</p> <p>Example:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">ansible.extra_vars = { + ntp_server: "pool.ntp.org", + nginx: { + port: 8008, + workers: 4 + } +} +</pre></div> +<p>These variables take the highest precedence over any other variables.</p> </li> <li> +<p><a href="#galaxy_command"><code>galaxy_command</code></a> (template string) - The command pattern used to install Galaxy roles when <code>galaxy_role_file</code> is set.</p> <p>The following (optional) placeholders can be used in this command pattern:</p> <ul> <li> +<a href="#role_file-"><code>%{role_file}</code></a> is replaced by the absolute path to the <code>galaxy_role_file</code> option </li> <li> +<a href="#roles_path-"><code>%{roles_path}</code></a> is <ul> <li>replaced by the absolute path to the <code>galaxy_roles_path</code> option when such option is defined, or </li> <li>replaced by the absolute path to a <code>roles</code> subdirectory sitting in the <code>playbook</code> parent directory. </li> </ul> </li> </ul> <p>By default, this option is set to</p> <p><code>ansible-galaxy install --role-file=%{role_file} --roles-path=%{roles_path} --force</code></p> </li> <li> +<p><a href="#galaxy_role_file"><code>galaxy_role_file</code></a> (string) - The path to the Ansible Galaxy role file.</p> <p>By default, this option is set to <code>nil</code> and Galaxy support is then disabled.</p> <p>Note: if an absolute path is given, the <code>ansible_local</code> provisioner will assume that it corresponds to the exact location on the guest system.</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">ansible.galaxy_role_file = "requirements.yml" +</pre></div> +</li> <li> +<p><a href="#galaxy_roles_path"><code>galaxy_roles_path</code></a> (string) - The path to the directory where Ansible Galaxy roles must be installed</p> <p>By default, this option is set to <code>nil</code>, which means that the Galaxy roles will be installed in a <code>roles</code> subdirectory located in the parent directory of the <code>playbook</code> file.</p> </li> <li> +<p><a href="#groups"><code>groups</code></a> (hash) - Set of inventory groups to be included in the <a href="ansible_intro">auto-generated inventory file</a>.</p> <p>Example:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">ansible.groups = { + "web" => ["vm1", "vm2"], + "db" => ["vm3"] +} +</pre></div> +<p>Example with <a href="https://docs.ansible.com/ansible/intro_inventory.html#group-variables">group variables</a>:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">ansible.groups = { + "atlanta" => ["host1", "host2"], + "atlanta:vars" => {"ntp_server" => "ntp.atlanta.example.com", + "proxy" => "proxy.atlanta.example.com"} +} +</pre></div> +<p>Notes:</p> <ul> <li>Alphanumeric patterns are not supported (e.g. <code>db-[a:f]</code>, <code>vm[01:10]</code>). </li> <li>This option has no effect when the <code>inventory_path</code> option is defined. </li> </ul> </li> <li> +<p><a href="#host_vars"><code>host_vars</code></a> (hash) - Set of inventory host variables to be included in the <a href="https://docs.ansible.com/ansible/intro_inventory.html#host-variables">auto-generated inventory file</a>.</p> <p>Example:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">ansible.host_vars = { + "host1" => {"http_port" => 80, + "maxRequestsPerChild" => 808}, + "comments" => "text with spaces", + "host2" => {"http_port" => 303, + "maxRequestsPerChild" => 909} +} +</pre></div> +<p>Note: This option has no effect when the <code>inventory_path</code> option is defined.</p> </li> <li> +<p><a href="#inventory_path"><code>inventory_path</code></a> (string) - The path to an Ansible inventory resource (e.g. a <a href="https://docs.ansible.com/intro_inventory.html">static inventory file</a>, a <a href="https://docs.ansible.com/intro_dynamic_inventory.html">dynamic inventory script</a> or even <a href="https://docs.ansible.com/intro_dynamic_inventory.html#using-multiple-inventory-sources">multiple inventories stored in the same directory</a>).</p> <p>By default, this option is disabled and Vagrant generates an inventory based on the <code>Vagrantfile</code> information.</p> </li> <li> +<p><a href="#limit"><code>limit</code></a> (string or array of strings) - Set of machines or groups from the inventory file to further control which hosts <a href="https://docs.ansible.com/glossary.html#limit-groups">are affected</a>.</p> <p>The default value is set to the machine name (taken from <code>Vagrantfile</code>) to ensure that <code>vagrant provision</code> command only affect the expected machine.</p> <p>Setting <code>limit = "all"</code> can be used to make Ansible connect to all machines from the inventory file.</p> </li> <li> +<p><a href="#playbook_command"><code>playbook_command</code></a> (string) - The command used to run playbooks.</p> <p>The default value is <code>ansible-playbook</code></p> </li> <li> +<p><a href="#raw_arguments"><code>raw_arguments</code></a> (array of strings) - a list of additional <code>ansible-playbook</code> arguments.</p> <p>It is an <em>unsafe wildcard</em> that can be used to apply Ansible options that are not (yet) supported by this Vagrant provisioner. As of Vagrant 1.7, <code>raw_arguments</code> has the highest priority and its values can potentially override or break other Vagrant settings.</p> <p>Examples:</p> <ul> <li> +<a href="#39-check-39-39-m-39-39-my-modules-39-"><code>['--check', '-M', '/my/modules']</code></a> </li> <li> +<a href="#quot-connection-paramiko-quot-quot-forks-10-quot-"><code>["--connection=paramiko", "--forks=10"]</code></a> </li> </ul> <blockquote class="alert alert-warn"> <p><strong>Attention:</strong> The <code>ansible</code> provisioner does not support whitespace characters in <code>raw_arguments</code> elements. Therefore <strong>don't write</strong> something like <code>["-c paramiko"]</code>, which will result with an invalid <code>" paramiko"</code> parameter value.</p> </blockquote> +</li> <li> +<p><a href="#skip_tags"><code>skip_tags</code></a> (string or array of strings) - Only plays, roles and tasks that <a href="https://docs.ansible.com/playbooks_tags.html"><em>do not match</em> these values will be executed</a>.</p> </li> <li> +<p><a href="#start_at_task"><code>start_at_task</code></a> (string) - The task name where the <a href="https://docs.ansible.com/playbooks_startnstep.html#start-at-task">playbook execution will start</a>.</p> </li> <li> +<p><a href="#sudo"><code>sudo</code></a> (boolean) - Backwards compatible alias for the <a href="#become"><code>become</code></a> option.</p> <blockquote class="alert alert-warning"> <p><strong>Deprecation:</strong> The <code>sudo</code> option is deprecated and will be removed in a future release. Please use the <a href="#become"><strong><code>become</code></strong></a> option instead.</p> </blockquote> +</li> <li> +<p><a href="#sudo_user"><code>sudo_user</code></a> (string) - Backwards compatible alias for the <a href="#become_user"><code>become_user</code></a> option.</p> <blockquote class="alert alert-warning"> <p><strong>Deprecation:</strong> The <code>sudo_user</code> option is deprecated and will be removed in a future release. Please use the <a href="#become_user"><strong><code>become_user</code></strong></a> option instead.</p> </blockquote> +</li> <li> +<p><a href="#tags"><code>tags</code></a> (string or array of strings) - Only plays, roles and tasks <a href="https://docs.ansible.com/playbooks_tags.html">tagged with these values will be executed</a> .</p> </li> <li> +<p><a href="#vault_password_file"><code>vault_password_file</code></a> (string) - The path of a file containing the password used by <a href="https://docs.ansible.com/playbooks_vault.html#vault">Ansible Vault</a>.</p> </li> <li> +<p><a href="#verbose"><code>verbose</code></a> (boolean or string) - Set Ansible's verbosity to obtain detailed logging</p> <p>Default value is <code>false</code> (minimal verbosity).</p> <p>Examples: <code>true</code> (equivalent to <code>v</code>), <code>-vvv</code> (equivalent to <code>vvv</code>), <code>vvvv</code>.</p> <p>Note that when the <code>verbose</code> option is enabled, the <code>ansible-playbook</code> command used by Vagrant will be displayed.</p> </li> <li> +<p><a href="#version"><code>version</code></a> (string) - The expected Ansible version.</p> <p>This option is disabled by default.</p> <p>When an Ansible version is defined (e.g. <code>"2.1.6.0"</code>), the Ansible provisioner will be executed only if Ansible is installed at the requested version.</p> <p>When this option is set to <code>"latest"</code>, no version check is applied.</p> <blockquote class="alert alert-info"> <p><strong>Tip:</strong> With the <code>ansible_local</code> provisioner, it is currently possible to use this option to specify which version of Ansible must be automatically installed, but <strong>only</strong> in combination with the <a href="ansible_local#install_mode"><strong><code>install_mode</code></strong></a> set to <strong><code>:pip</code></strong>.</p> </blockquote> +</li> </ul><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/provisioning/ansible_common.html" class="_attribution-link">https://www.vagrantup.com/docs/provisioning/ansible_common.html</a> + </p> +</div> diff --git a/devdocs/vagrant/provisioning%2Fansible_intro.html b/devdocs/vagrant/provisioning%2Fansible_intro.html new file mode 100644 index 00000000..98427e42 --- /dev/null +++ b/devdocs/vagrant/provisioning%2Fansible_intro.html @@ -0,0 +1,132 @@ +<h1 id="ansible-and-vagrant"> Ansible and Vagrant </h1> <p>The information below is applicable to both Vagrant Ansible provisioners:</p> <ul> <li> +<a href="ansible"><code>ansible</code></a>, where Ansible is executed on the <strong>Vagrant host</strong> </li> <li> +<a href="ansible_local"><code>ansible_local</code></a>, where Ansible is executed on the <strong>Vagrant guest</strong> </li> </ul> <p>The list of common options for these two provisioners is documented in a <a href="ansible_common">separate documentation page</a>.</p> <p>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.</p> <p>To learn more about Ansible, please consult the <a href="https://docs.ansible.com/">Ansible Documentation Site</a>.</p> <h2 id="the-playbook-file"> The Playbook File </h2> <p>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 <a href="https://docs.ansible.com/playbooks.html">playbook documentation</a> goes into great detail on how to author playbooks, and there are a number of <a href="https://docs.ansible.com/playbooks_best_practices.html">best practices</a> that can be applied to use Ansible's powerful features effectively.</p> <p>A playbook that installs and starts (or restarts) the NTP daemon via YUM looks like:</p> <div class="highlight"><pre class="highlight plaintext">--- +- 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 +</pre></div> +<p>You can of course target other operating systems that do not have YUM by changing the playbook tasks. Ansible ships with a number of <a href="https://docs.ansible.com/modules.html">modules</a> that make running otherwise tedious tasks dead simple.</p> <h3 id="running-ansible"> Running Ansible </h3> <p>The <code>playbook</code> option is strictly required by both Ansible provisioners (<a href="ansible"><code>ansible</code></a> and <a href="ansible_local"><code>ansible_local</code></a>), as illustrated in this basic Vagrantfile` configuration:</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<p>Since an Ansible playbook can include many files, you may also collect the related files in a <a href="https://docs.ansible.com/playbooks_best_practices.html#directory-layout">directory structure</a> like this:</p> <div class="highlight"><pre class="highlight plaintext">. +|-- Vagrantfile +|-- provisioning +| |-- group_vars +| |-- all +| |-- roles +| |-- bar +| |-- foo +| |-- playbook.yml +</pre></div> +<p>In such an arrangement, the <code>ansible.playbook</code> path should be adjusted accordingly:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "ansible" do |ansible| + ansible.playbook = "provisioning/playbook.yml" + end +end +</pre></div> +<h2 id="the-inventory-file"> The Inventory File </h2> <p>When using Ansible, it needs to know on which machines a given playbook should run. It does this by way of an <a href="https://docs.ansible.com/intro_inventory.html">inventory</a> file which lists those machines. In the context of Vagrant, there are two ways to approach working with inventory files.</p> <h3 id="auto-generated-inventory"> Auto-Generated Inventory </h3> <p>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.</p> <h4 id="example-with-the-ansible-provisioner"> Example with the <a href="ansible"><code>ansible</code></a> provisioner </h4> <div class="highlight"><pre class="highlight plaintext"># 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' +</pre></div> +<p>Note that the generated inventory file is stored as part of your local Vagrant environment in <code>.vagrant/provisioners/ansible/inventory/vagrant_ansible_inventory</code>.</p> <h4 id="example-with-the-ansible_local-provisioner"> Example with the <a href="ansible_local"><code>ansible_local</code></a> provisioner </h4> <div class="highlight"><pre class="highlight plaintext"># Generated by Vagrant + +default ansible_connection=local +</pre></div> +<p>Note that the generated inventory file is uploaded to the guest VM in a subdirectory of <a href="ansible_local"><code>tmp_path</code></a>, e.g. <code>/tmp/vagrant-ansible/inventory/vagrant_ansible_local_inventory</code>.</p> <h4 id="host-variables"> Host Variables </h4> <p>As of Vagrant 1.8.0, the <a href="ansible_common#host_vars"><code>host_vars</code></a> option can be used to set <a href="https://docs.ansible.com/ansible/intro_inventory.html#host-variables">variables for individual hosts</a> in the generated inventory file (see also the notes on group variables below).</p> <p>With this configuration example:</p> <div class="highlight"><pre class="highlight plaintext">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 +</pre></div> +<p>Vagrant would generate the following inventory file:</p> <div class="highlight"><pre class="highlight plaintext"># Generated by Vagrant + +host1 ansible_ssh_host=... http_port=80 maxRequestsPerChild=808 +host2 ansible_ssh_host=... http_port=303 maxRequestsPerChild=909 +</pre></div> +<h4 id="groups-and-group-variables"> Groups and Group Variables </h4> <p>The <a href="ansible_common#groups"><code>groups</code></a> option can be used to pass a hash of group names and group members to be included in the generated inventory file.</p> <p>As of Vagrant 1.8.0, it is also possible to specify <a href="https://docs.ansible.com/ansible/intro_inventory.html#group-variables">group variables</a>, and group members as <a href="https://docs.ansible.com/ansible/intro_inventory.html#hosts-and-groups">host ranges (with numeric or alphabetic patterns)</a>.</p> <p>With this configuration example:</p> <div class="highlight"><pre class="highlight plaintext">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 +</pre></div> +<p>Vagrant would generate the following inventory file:</p> <div class="highlight"><pre class="highlight plaintext"># 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 +</pre></div> +<p><strong>Notes:</strong></p> <ul> <li>Prior to Vagrant 1.7.3, the <code>ansible_ssh_private_key_file</code> variable was not set in generated inventory, but passed as command line argument to <code>ansible-playbook</code> command. </li> <li>The generation of group variables blocks (e.g. <code>[group1:vars]</code>) is only possible since Vagrant 1.8.0. Note however that setting variables directly in the inventory is not the <a href="https://docs.ansible.com/intro_inventory.html#splitting-out-host-and-group-specific-data">preferred practice in Ansible</a>. If possible, group (or host) variables should be set in <code>YAML</code> files stored in the <code>group_vars/</code> or <code>host_vars/</code> directories in the playbook (or inventory) directory instead. </li> <li> +<p>Unmanaged machines and undefined groups are not added to the inventory, to avoid useless Ansible errors (e.g. <em>unreachable host</em> or <em>undefined child group</em>)</p> <p>For example, <code>machine3</code> and <code>group3</code> in the example below would not be added to the generated inventory file:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">ansible.groups = { + "group1" => ["machine1"], + "group2" => ["machine2", "machine3"], + "all_groups:children" => ["group1", "group2", "group3"] +} +</pre></div> +</li> <li> +<p><a href="https://docs.ansible.com/ansible/intro_inventory.html#hosts-and-groups">Host range patterns (numeric and alphabetic ranges)</a> 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 <em>unreachable host</em>).</p> </li> </ul> <h3 id="static-inventory"> Static Inventory </h3> <p>The second option is for situations where you would like to have more control over the inventory management.</p> <p>With the <a href="ansible_common#inventory_path"><code>inventory_path</code></a> option, you can reference a specific inventory resource (e.g. a static inventory file, a <a href="https://docs.ansible.com/intro_dynamic_inventory.html">dynamic inventory script</a> or even <a href="https://docs.ansible.com/intro_dynamic_inventory.html#using-multiple-inventory-sources">multiple inventories stored in the same directory</a>). Vagrant will then use this inventory information instead of generating it.</p> <p>A very simple inventory file for use with Vagrant might look like:</p> <div class="highlight"><pre class="highlight plaintext">default ansible_ssh_host=192.168.111.222 +</pre></div> +<p>Where the above IP address is one set in your Vagrantfile:</p> <div class="highlight"><pre class="highlight plaintext">config.vm.network :private_network, ip: "192.168.111.222" +</pre></div> +<p><strong>Notes:</strong></p> <ul> <li>The machine names in <code>Vagrantfile</code> and <code>ansible.inventory_path</code> files should correspond, unless you use <code>ansible.limit</code> option to reference the correct machines. </li> <li>The SSH host addresses (and ports) must obviously be specified twice, in <code>Vagrantfile</code> and <code>ansible.inventory_path</code> files. </li> <li>Sharing hostnames across Vagrant host and guests might be a good idea (e.g. with some Ansible configuration task, or with a plugin like <a href="https://github.com/smdahlen/vagrant-hostmanager"><code>vagrant-hostmanager</code></a>). </li> </ul> <h3 id="the-ansible-configuration-file"> The Ansible Configuration File </h3> <p>Certain settings in Ansible are (only) adjustable via a <a href="https://docs.ansible.com/intro_configuration.html">configuration file</a>, and you might want to ship such a file in your Vagrant project.</p> <p>When shipping an Ansible configuration file it is good to know that:</p> <ul> <li>as of Ansible 1.5, the lookup order is the following: <ul> <li>any path set as <code>ANSIBLE_CONFIG</code> environment variable </li> <li> +<a href="#ansible-cfg"><code>ansible.cfg</code></a> in the runtime working directory </li> <li> +<a href="#ansible-cfg-1"><code>.ansible.cfg</code></a> in the user home directory </li> <li> +<a href="#etc-ansible-ansible-cfg"><code>/etc/ansible/ansible.cfg</code></a> </li> </ul> </li> <li>Ansible commands don't look for a configuration file relative to the playbook file location (e.g. in the same directory) </li> <li>an <code>ansible.cfg</code> file located in the same directory as your <code>Vagrantfile</code> will be used by default. </li> <li>it is also possible to reference any other location with the <a href="ansible_common#config_file">config_file</a> provisioner option. In this case, Vagrant will set the <code>ANSIBLE_CONFIG</code> environment variable accordingly. </li> </ul><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/provisioning/ansible_intro.html" class="_attribution-link">https://www.vagrantup.com/docs/provisioning/ansible_intro.html</a> + </p> +</div> diff --git a/devdocs/vagrant/provisioning%2Fansible_local.html b/devdocs/vagrant/provisioning%2Fansible_local.html new file mode 100644 index 00000000..48742f8b --- /dev/null +++ b/devdocs/vagrant/provisioning%2Fansible_local.html @@ -0,0 +1,99 @@ +<h1 id="ansible-local-provisioner"> Ansible Local Provisioner </h1> <p><strong>Provisioner name: <code>ansible_local</code></strong></p> <p>The Vagrant Ansible Local provisioner allows you to provision the guest using <a href="http://ansible.com">Ansible</a> playbooks by executing <strong><code>ansible-playbook</code> directly on the guest machine</strong>.</p> <blockquote class="alert alert-warning"> <p><strong>Warning:</strong> If you are not familiar with Ansible and Vagrant already, I recommend starting with the <a href="shell">shell provisioner</a>. However, if you are comfortable with Vagrant already, Vagrant is a great way to learn Ansible.</p> </blockquote> +<h2 id="setup-requirements"> Setup Requirements </h2> <p>The main advantage of the Ansible Local provisioner in comparison to the <a href="ansible">Ansible (remote) provisioner</a> is that it does not require any additional software on your Vagrant host.</p> <p>On the other hand, <a href="https://docs.ansible.com/intro_installation.html#installing-the-control-machine">Ansible must obviously be installed</a> on your guest machine(s).</p> <p><strong>Note:</strong> By default, Vagrant will <em>try</em> to automatically install Ansible if it is not yet present on the guest machine (see the <code>install</code> option below for more details).</p> <h2 id="usage"> Usage </h2> <p>This page only documents the specific parts of the <code>ansible_local</code> provisioner. General Ansible concepts like Playbook or Inventory are shortly explained in the <a href="ansible_intro">introduction to Ansible and Vagrant</a>.</p> <p>The Ansible Local provisioner requires that all the Ansible Playbook files are available on the guest machine, at the location referred by the <code>provisioning_path</code> 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 <a href="../synced-folders/index">Synced Folder</a>.</p> <h3 id="simplest-configuration"> Simplest Configuration </h3> <p>To run Ansible from your Vagrant guest, the basic <code>Vagrantfile</code> configuration looks like:</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<p><strong>Requirements:</strong></p> <ul> <li> +<p>The <code>playbook.yml</code> file is stored in your Vagrant's project home directory.</p> </li> <li> +<p>The <a href="../synced-folders/basic_usage">default shared directory</a> is enabled (<code>.</code> → <code>/vagrant</code>).</p> </li> </ul> <h2 id="options"> Options </h2> <p>This section lists the <em>specific</em> options for the Ansible Local provisioner. In addition to the options listed below, this provisioner supports the <a href="ansible_common"><strong>common options</strong> for both Ansible provisioners</a>.</p> <ul> <li> +<p><a href="#install"><code>install</code></a> (boolean) - Try to automatically install Ansible on the guest system.</p> <p>This option is enabled by default.</p> <p>Vagrant will try to install (or upgrade) Ansible when one of these conditions are met:</p> <ul> <li>Ansible is not installed (or cannot be found). </li> <li>The <a href="ansible_common#version"><code>version</code></a> option is set to <code>"latest"</code>. </li> <li>The current Ansible version does not correspond to the <a href="ansible_common#version"><code>version</code></a> option. </li> </ul> <blockquote class="alert alert-warning"> <p><strong>Attention:</strong> There is no guarantee that this automated installation will replace a custom Ansible setup, that might be already present on the Vagrant box.</p> </blockquote> +</li> <li> +<p><a href="#install_mode"><code>install_mode</code></a> (<code>:default</code>, <code>:pip</code>, or <code>:pip_args_only</code>) - Select the way to automatically install Ansible on the guest system.</p> <ul> <li> +<a href="#default"><code>:default</code></a>: Ansible is installed from the operating system package manager. This mode doesn't support <code>version</code> selection. For many platforms (e.g Debian, FreeBSD, OpenSUSE) the official package repository is used, except for the following Linux distributions: <ul> <li>On Ubuntu-like systems, the latest Ansible release is installed from the <code>ppa:ansible/ansible</code> repository. The compatibility is maintained only for active long-term support (LTS) versions. </li> <li>On RedHat-like systems, the latest Ansible release is installed from the <a href="http://fedoraproject.org/wiki/EPEL">EPEL</a> repository. </li> </ul> </li> <li> +<p><a href="#pip"><code>:pip</code></a>: Ansible is installed from <a href="https://pypi.python.org/pypi">PyPI</a> with <a href="https://pip.pypa.io">pip</a> package installer. With this mode, Vagrant will systematically try to <a href="https://pip.pypa.io/en/stable/installing/#installing-with-get-pip-py">install the latest pip version</a>. With the <code>:pip</code> mode you can optionally install a specific Ansible release by setting the <a href="ansible_common#version"><code>version</code></a> option.</p> <p>Example:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.provision "ansible_local" do |ansible| + ansible.playbook = "playbook.yml" + ansible.install_mode = "pip" + ansible.version = "2.2.1.0" +end +</pre></div> +<p>With this configuration, Vagrant will install <code>pip</code> and then execute the command</p> <div class="highlight"><pre class="highlight shell" data-language="shell">sudo pip install --upgrade ansible==2.2.1.0 +</pre></div> +</li> <li> +<p><a href="#pip_args_only"><code>:pip_args_only</code></a>: This mode is very similar to the <code>:pip</code> mode, with the difference that in this case no pip arguments will be automatically set by Vagrant.</p> <p>Example:</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<p>With this configuration, Vagrant will install <code>pip</code> and then execute the command</p> <div class="highlight"><pre class="highlight shell" data-language="shell">sudo pip install -r /vagrant/requirements.txt +</pre></div> +</li> </ul> <p>The default value of <code>install_mode</code> is <code>:default</code>, and any invalid value for this option will silently fall back to the default value.</p> </li> <li> +<p><a href="#pip_args"><code>pip_args</code></a> (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, <a href="https://pip.pypa.io/en/stable/reference/pip_install/#cmdoption-i"><code>--index-url</code></a>).</p> <p>By default, this option is not set.</p> <p>Example:</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<p>With this configuration, Vagrant will install <code>pip</code> and then execute the command</p> <div class="highlight"><pre class="highlight shell" data-language="shell">sudo pip install --index-url https://pypi.internal --upgrade ansible +</pre></div> +</li> <li> +<p><a href="#provisioning_path"><code>provisioning_path</code></a> (string) - An absolute path on the guest machine where the Ansible files are stored. The <code>ansible-galaxy</code> and <code>ansible-playbook</code> commands are executed from this directory. This is the location to place an <a href="http://docs.ansible.com/ansible/intro_configuration.html">ansible.cfg</a> file, in case you need it.</p> <p>The default value is <code>/vagrant</code>.</p> </li> <li> +<p><a href="#tmp_path"><code>tmp_path</code></a> (string) - An absolute path on the guest machine where temporary files are stored by the Ansible Local provisioner.</p> <p>The default value is <code>/tmp/vagrant-ansible</code></p> </li> </ul> <h2 id="tips-and-tricks"> Tips and Tricks </h2> <h3 id="install-galaxy-roles-in-a-path-owned-by-root"> Install Galaxy Roles in a path owned by root </h3> +<blockquote class="alert alert-warning"> <strong>Disclaimer:</strong> 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. </blockquote> <p>Be careful that <code>ansible-galaxy</code> command is executed by default as vagrant user. Setting <code>galaxy_roles_path</code> to a folder like <code>/etc/ansible/roles</code> will fail, and <code>ansible-galaxy</code> will extract the role a second time in <code>/home/vagrant/.ansible/roles/</code>. Then if your playbook uses <code>become</code> to run as <code>root</code>, it will fail with a <em>"role was not found"</em> error.</p> <p>To work around that, you can use <code>ansible.galaxy_command</code> to prepend the command with <code>sudo</code>, as illustrated in the example below:</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<h3 id="ansible-parallel-execution-from-a-guest"> Ansible Parallel Execution from a Guest </h3> <p>With the following configuration pattern, you can install and execute Ansible only on a single guest machine (the <code>"controller"</code>) to provision all your machines.</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<p>You need to create a static <code>inventory</code> file that corresponds to your <code>Vagrantfile</code> machine definitions:</p> <div class="highlight"><pre class="highlight plaintext">controller ansible_connection=local +node1 ansible_ssh_host=172.17.177.21 ansible_ssh_private_key_file=/vagrant/.vagrant/machines/node1/virtualbox/private_key +node2 ansible_ssh_host=172.17.177.22 ansible_ssh_private_key_file=/vagrant/.vagrant/machines/node2/virtualbox/private_key + +[nodes] +node[1:2] +</pre></div> +<p>And finally, you also have to create an <a href="https://docs.ansible.com/intro_configuration.html#openssh-specific-settings"><code>ansible.cfg</code> file</a> to fully disable SSH host key checking. More SSH configurations can be added to the <code>ssh_args</code> parameter (e.g. agent forwarding, etc.)</p> <div class="highlight"><pre class="highlight plaintext">[defaults] +host_key_checking = no + +[ssh_connection] +ssh_args = -o ControlMaster=auto -o ControlPersist=60s -o UserKnownHostsFile=/dev/null -o IdentitiesOnly=yes +</pre></div><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/provisioning/ansible_local.html" class="_attribution-link">https://www.vagrantup.com/docs/provisioning/ansible_local.html</a> + </p> +</div> diff --git a/devdocs/vagrant/provisioning%2Fbasic_usage.html b/devdocs/vagrant/provisioning%2Fbasic_usage.html new file mode 100644 index 00000000..08a830b0 --- /dev/null +++ b/devdocs/vagrant/provisioning%2Fbasic_usage.html @@ -0,0 +1,83 @@ +<h1 id="basic-usage-of-provisioners"> Basic Usage of Provisioners </h1> <p>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.</p> <h2 id="configuration"> Configuration </h2> <p>First, every provisioner is configured within your <a href="../vagrantfile/index">Vagrantfile</a> using the <code>config.vm.provision</code> method call. For example, the Vagrantfile below enables shell provisioning:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + # ... other configuration + + config.vm.provision "shell", inline: "echo hello" +end +</pre></div> +<p>Every provisioner has a type, such as <code>"shell"</code>, 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:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + # ... other configuration + + config.vm.provision "shell" do |s| + s.inline = "echo hello" + end +end +</pre></div> +<p>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.</p> <p>The attributes that can be set in a single-line are the attributes that are set with the <code>=</code> style, such as <code>inline = "echo hello"</code> above. If the style is instead more of a function call, such as <code>add_recipe "foo"</code>, then this cannot be specified in a single line.</p> <p>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:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + # ... other configuration + + config.vm.provision "bootstrap", type: "shell" do |s| + s.inline = "echo hello" + end +end +</pre></div> +<p>Naming provisioners is simple. The first argument to <code>config.vm.provision</code> becomes the name, and then a <code>type</code> option is used to specify the provisioner type, such as <code>type: "shell"</code> above.</p> <h2 id="running-provisioners"> Running Provisioners </h2> <p>Provisioners are run in three cases: the initial <code>vagrant up</code>, <code>vagrant +provision</code>, and <code>vagrant reload --provision</code>.</p> <p>A <code>--no-provision</code> flag can be passed to <code>up</code> and <code>reload</code> if you do not want to run provisioners. Likewise, you can pass <code>--provision</code> to force provisioning.</p> <p>The <code>--provision-with</code> 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 <code>vagrant provision --provision-with shell</code>. The arguments to <code>--provision-with</code> can be the provisioner type (such as "shell") or the provisioner name (such as "bootstrap" from above).</p> <h2 id="run-once-always-or-never"> Run Once, Always or Never </h2> <p>By default, provisioners are only run once, during the first <code>vagrant up</code> since the last <code>vagrant destroy</code>, unless the <code>--provision</code> flag is set, as noted above.</p> <p>Optionally, you can configure provisioners to run on every <code>up</code> or <code>reload</code>. They will only be not run if the <code>--no-provision</code> flag is explicitly specified. To do this set the <code>run</code> option to "always", as shown below:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "shell", inline: "echo hello", + run: "always" +end +</pre></div> +<p>You can also set <code>run:</code> to <code>"never"</code> 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 <code>vagrant provision --provision-with bootstrap</code>.</p> <p>If you are using the block format, you must specify it outside of the block, as shown below:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "bootstrap", type: "shell", run: "never" do |s| + s.inline = "echo hello" + end +end +</pre></div> +<h2 id="multiple-provisioners"> Multiple Provisioners </h2> <p>Multiple <code>config.vm.provision</code> 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.</p> <p>If you define provisioners at multiple "scope" levels (such as globally in the configuration block, then in a <a href="../multi-machine/index">multi-machine</a> definition, then maybe in a <a href="../providers/configuration">provider-specific override</a>), then the outer scopes will always run <em>before</em> any inner scopes. For example, in the Vagrantfile below:</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<p>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 <em>outside in</em>.</p> <p>With multiple provisioners, use the <code>--provision-with</code> setting along with names to get more fine grained control over what is run and when.</p> <h2 id="overriding-provisioner-settings"> Overriding Provisioner Settings </h2> <blockquote class="alert alert-warning"> <p><strong>Warning: Advanced Topic!</strong> 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.</p> </blockquote> +<p>When using features such as <a href="../multi-machine/index">multi-machine</a> or <a href="../providers/configuration">provider-specific overrides</a>, 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.</p> <p>To override settings, you must assign a name to your provisioner.</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<p>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.</p> <p><strong>Be careful with ordering.</strong> When overriding a provisioner in a sub-scope, the provisioner will run at <em>that point</em>. In the example below, the output would be "foo" then "bar":</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<p>If you want to preserve the original ordering, you can specify the <code>preserve_order: true</code> flag:</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/provisioning/basic_usage.html" class="_attribution-link">https://www.vagrantup.com/docs/provisioning/basic_usage.html</a> + </p> +</div> diff --git a/devdocs/vagrant/provisioning%2Fcfengine.html b/devdocs/vagrant/provisioning%2Fcfengine.html new file mode 100644 index 00000000..95394d81 --- /dev/null +++ b/devdocs/vagrant/provisioning%2Fcfengine.html @@ -0,0 +1,43 @@ +<h1 id="cfengine-provisioner"> CFEngine Provisioner </h1> <p><strong>Provisioner name: <code>cfengine</code></strong></p> <p>The Vagrant CFEngine provisioner allows you to provision the guest using <a href="https://cfengine.com/">CFEngine</a>. It can set up both CFEngine policy servers and clients. You can configure both the policy server and the clients in a single <a href="../multi-machine/index">multi-machine <code>Vagrantfile</code></a>.</p> <blockquote class="alert alert-warning"> <p><strong>Warning:</strong> If you are not familiar with CFEngine and Vagrant already, I recommend starting with the <a href="shell">shell provisioner</a>. However, if you are comfortable with Vagrant already, Vagrant is the best way to learn CFEngine.</p> </blockquote> +<p>Let us look at some common examples first. See the bottom of this document for a comprehensive list of options.</p> <h2 id="setting-up-a-cfengine-server-and-client"> Setting up a CFEngine server and client </h2> <p>The CFEngine provisioner automatically installs the latest <a href="https://cfengine.com/cfengine-linux-distros">CFEngine Community packages</a> on the VM, then configures and starts CFEngine according to your specification.</p> <p>Configuring a VM as a CFEngine policy server is easy:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "cfengine" do |cf| + cf.am_policy_hub = true + end +end +</pre></div> +<p>The host will automatically be <a href="https://cfengine.com/docs/3.5/manuals-architecture-networking.html#bootstrapping">bootstrapped</a> to itself to become a policy server.</p> <p>If you already have a working CFEngine policy server, you can get a CFEngine client installed and bootstrapped by specifying its IP address:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "cfengine" do |cf| + cf.policy_server_address = "10.0.2.15" + end +end +</pre></div> +<h2 id="copying-files-to-the-vm"> Copying files to the VM </h2> <p>If you have some policy or other files that you want to install by default on a VM, you can use the <code>files_path</code> attribute:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "cfengine" do |cf| + cf.am_policy_hub = true + cf.files_path = "cfengine_files" + end + end +</pre></div> +<p>Everything under <code>cfengine_files/</code> in the Vagrant project directory will be recursively copied under <code>/var/cfengine/</code> in the VM, on top of its default contents.</p> <p>A common use case is to add your own files to <code>/var/cfengine/masterfiles/</code> in the policy server. Assuming your extra files are stored under <code>cfengine_files/masterfiles/</code>, the line shown above will add them to the VM after CFEngine is installed, but before it is bootstrapped.</p> <h2 id="modes-of-operation"> Modes of operation </h2> <p>The default mode of operation is <code>:bootstrap</code>, which results in CFEngine being bootstrapped according to the information provided in the <code>Vagrantfile</code>. You can also set <code>mode</code> to <code>:single_run</code>, which will run <code>cf-agent</code> once on the host to execute the file specified in the <code>run_file</code> parameter, but will not bootstrap it, so it will not be executed periodically.</p> <p>The recommended mode of operation is <code>:bootstrap</code>, as you get the full benefits of CFEngine when you have it running periodically.</p> <h2 id="running-a-standalone-file"> Running a standalone file </h2> <p>If you want to run a standalone file, you can specify the <code>run_file</code> parameter. The file will be copied to the VM and executed on its own using <code>cf-agent</code>. Note that the file needs to be a standalone policy, including its own <a href="https://cfengine.com/docs/3.5/reference-components.html#common-control"><code>body common control</code></a>.</p> <p>The <code>run_file</code> parameter is mandatory if <code>mode</code> is set to <code>:single_run</code>, but can also be specified when <code>mode</code> is set to <code>:bootstrap</code> - in this case the file will be executed after the host has been bootstrapped.</p> <h2 id="full-alphabetical-list-of-configuration-options"> Full Alphabetical List of Configuration Options </h2> <ul> <li> +<a href="#am_policy_hub"><code>am_policy_hub</code></a> (boolean, default <code>false</code>) determines whether the VM will be configured as a CFEngine policy hub (automatically bootstrapped to its own IP address). You can combine it with <code>policy_server_address</code> if the VM has multiple network interfaces and you want to bootstrap to a specific one. </li> <li> +<a href="#extra_agent_args"><code>extra_agent_args</code></a> (string, default <code>nil</code>) can be used to pass additional arguments to <code>cf-agent</code> when it is executed. For example, you could use it to pass the <code>-I</code> or <code>-v</code> options to enable additional output from the agent. </li> <li> +<a href="#classes"><code>classes</code></a> (array, default <code>nil</code>) can be used to define additional classes during <code>cf-agent</code> runs. These classes will be defined using the <code>-D</code> option to <code>cf-agent</code>. </li> <li> +<a href="#deb_repo_file"><code>deb_repo_file</code></a> (string, default <code>"/etc/apt/sources.list.d/cfengine-community.list"</code>) specifies the file in which the CFEngine repository information will be stored in Debian systems. </li> <li> +<a href="#deb_repo_line"><code>deb_repo_line</code></a> (string, default <code>"deb https://cfengine.com/pub/apt +$(lsb_release -cs) main"</code>) specifies the repository to use for <code>.deb</code> packages. </li> <li> +<a href="#files_path"><code>files_path</code></a> (string, default <code>nil</code>) specifies a directory that will be copied to the VM on top of the default <code>/var/cfengine/</code> (the contents of <code>/var/cfengine/</code> will not be replaced, the files will added to it). </li> <li> +<a href="#force_bootstrap"><code>force_bootstrap</code></a> (boolean, default <code>false</code>) specifies whether CFEngine will be bootstrapped again even if the host has already been bootstrapped. </li> <li> +<a href="#install"><code>install</code></a> (boolean or <code>:force</code>, default <code>true</code>) specifies whether CFEngine will be installed on the VM if needed. If you set this parameter to <code>:force</code>, then CFEngine will be reinstalled even if it is already present on the machine. </li> <li> +<a href="#mode"><code>mode</code></a> (<code>:bootstrap</code> or <code>:single_run</code>, default <code>:bootstrap</code>) specifies whether CFEngine will be bootstrapped so that it executes periodically, or will be run a single time. If <code>mode</code> is set to <code>:single_run</code> you have to set <code>run_file</code>. </li> <li> +<a href="#policy_server_address"><code>policy_server_address</code></a> (string, no default) specifies the IP address of the policy server to which CFEngine will be bootstrapped. If <code>am_policy_hub</code> is set to <code>true</code>, 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). </li> <li> +<a href="#repo_gpg_key_url"><code>repo_gpg_key_url</code></a> (string, default <code>"https://cfengine.com/pub/gpg.key"</code>) contains the URL to obtain the GPG key used to verify the packages obtained from the repository. </li> <li> +<a href="#run_file"><code>run_file</code></a> (string, default <code>nil</code>) can be used to specify a file inside the Vagrant project directory that will be copied to the VM and executed once using <code>cf-agent</code>. This parameter is mandatory if <code>mode</code> is set to <code>:single_run</code>, but can also be specified when <code>mode</code> is set to <code>:bootstrap</code> - in this case the file will be executed after the host has been bootstrapped. </li> <li> +<a href="#upload_path"><code>upload_path</code></a> (string, default <code>"/tmp/vagrant-cfengine-file"</code>) specifies the file to which <code>run_file</code> (if specified) will be copied on the VM before being executed. </li> <li> +<a href="#yum_repo_file"><code>yum_repo_file</code></a> (string, default <code>"/etc/yum.repos.d/cfengine-community.repo"</code>) specifies the file in which the CFEngine repository information will be stored in RedHat systems. </li> <li> +<a href="#yum_repo_url"><code>yum_repo_url</code></a> (string, default <code>"https://cfengine.com/pub/yum/"</code>) specifies the URL of the repository to use for <code>.rpm</code> packages. </li> <li> +<a href="#package_name"><code>package_name</code></a> (string, default <code>"cfengine-community"</code>) specifies the name of the package used to install CFEngine. </li> </ul><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/provisioning/cfengine.html" class="_attribution-link">https://www.vagrantup.com/docs/provisioning/cfengine.html</a> + </p> +</div> diff --git a/devdocs/vagrant/provisioning%2Fchef_apply.html b/devdocs/vagrant/provisioning%2Fchef_apply.html new file mode 100644 index 00000000..b701ee4e --- /dev/null +++ b/devdocs/vagrant/provisioning%2Fchef_apply.html @@ -0,0 +1,34 @@ +<h1 id="chef-apply-provisioner"> Chef Apply Provisioner </h1> <p><strong>Provisioner name: <code>chef_apply</code></strong></p> <p>The Vagrant Chef Apply provisioner allows you to provision the guest using <a href="https://www.getchef.com/">Chef</a>, specifically with <a href="https://docs.getchef.com/ctl_chef_apply.html">Chef Apply</a>.</p> <p>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.</p> <blockquote class="alert alert-warning"> <p><strong>Warning:</strong> If you are not familiar with Chef and Vagrant already, we recommend starting with the <a href="shell">shell provisioner</a>.</p> </blockquote> +<h2 id="options"> Options </h2> <p>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.</p> <ul> <li> +<p><a href="#recipe"><code>recipe</code></a> (string) - The raw recipe contents to execute using Chef Apply on the guest.</p> </li> <li> +<p><a href="#log_level"><code>log_level</code></a> (string) - The log level to use while executing <code>chef-apply</code>. The default value is "info".</p> </li> <li> +<p><a href="#upload_path"><code>upload_path</code></a> (string) - <strong>Advanced!</strong> 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 <code>/tmp/vagrant-chef-apply-#</code> where <code>#</code> is a unique counter generated by Vagrant to prevent collisions.</p> </li> </ul> <p>In addition to all the options listed above, the Chef Apply provisioner supports the <a href="chef_common">common options for all Chef provisioners</a>.</p> <h2 id="specifying-a-recipe"> Specifying a Recipe </h2> <p>The easiest way to get started with the Chef Apply provisioner is to just specify an inline <a href="https://docs.chef.io/recipes.html">Chef recipe</a>. For example:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "chef_apply" do |chef| + chef.recipe = "package[apache2]" + end +end +</pre></div> +<p>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.</p> <p>Since single-line Chef recipes are rare, you can also specify the recipe using a "heredoc":</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<p>Finally, if you would prefer to store the recipe as plain-text, you can set the recipe to the contents of a file:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "chef_apply" do |chef| + chef.recipe = File.read("/path/to/my/recipe.rb") + end +end +</pre></div> +<h2 id="roles"> Roles </h2> <p>The Vagrant Chef Apply provisioner does not support roles. Please use a different Vagrant Chef provisioner if you need support for roles.</p> <h2 id="data-bags"> Data Bags </h2> <p>The Vagrant Chef Apply provisioner does not support data_bags. Please use a different Vagrant Chef provisioner if you need support for data_bags.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/provisioning/chef_apply.html" class="_attribution-link">https://www.vagrantup.com/docs/provisioning/chef_apply.html</a> + </p> +</div> diff --git a/devdocs/vagrant/provisioning%2Fchef_client.html b/devdocs/vagrant/provisioning%2Fchef_client.html new file mode 100644 index 00000000..520ffa4c --- /dev/null +++ b/devdocs/vagrant/provisioning%2Fchef_client.html @@ -0,0 +1,42 @@ +<h1 id="chef-client-provisioner"> Chef Client Provisioner </h1> <p><strong>Provisioner name: <code>chef_client</code></strong></p> <p>The Vagrant Chef Client provisioner allows you to provision the guest using <a href="https://www.chef.io/chef/">Chef</a>, specifically by connecting to an existing Chef Server and registering the Vagrant machine as a node within your infrastructure.</p> <p>If you are just learning Chef for the first time, you probably want to start with the <a href="chef_solo">Chef Solo</a> provisioner.</p> <blockquote class="alert alert-warning"> <p><strong>Warning:</strong> If you are not familiar with Chef and Vagrant already, I recommend starting with the <a href="shell">shell provisioner</a>.</p> </blockquote> +<h2 id="authenticating"> Authenticating </h2> <p>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:</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<p>The node will register with the Chef Server specified, download the proper run list for that node, and provision.</p> <h2 id="specifying-a-run-list"> Specifying a Run List </h2> <p>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:</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<p>Remember, this will <em>override</em> the run list specified on the Chef server itself.</p> <h2 id="environments"> Environments </h2> <p>You can specify the <a href="https://docs.chef.io/environments.html">environment</a> for the node to come up in using the <code>environment</code> configuration option:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "chef_client" do |chef| + # ... + + chef.environment = "development" + end +end +</pre></div> +<h2 id="other-configuration-options"> Other Configuration Options </h2> <p>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.</p> <ul> <li> +<a href="#client_key_path"><code>client_key_path</code></a> </li> <li> +<a href="#node_name"><code>node_name</code></a> </li> <li> +<a href="#validation_client_name"><code>validation_client_name</code></a> </li> </ul> <p>In addition to all the options listed above, the Chef Client provisioner supports the <a href="chef_common">common options for all Chef provisioners</a>.</p> <h2 id="cleanup"> Cleanup </h2> <p>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:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">chef.delete_node = true +chef.delete_client = true +</pre></div> +<p>If you do not specify it or set it to <code>false</code>, 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 <code>knife</code> tool:</p> <div class="highlight"><pre class="highlight plaintext">$ knife node delete precise64 +$ knife client delete precise64 +</pre></div> +<p>If you fail to do so, you will get the following error when Vagrant tries to provision the machine with Chef Client:</p> <div class="highlight"><pre class="highlight plaintext">HTTP Request Returned 409 Conflict: Client already exists. +</pre></div><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/provisioning/chef_client.html" class="_attribution-link">https://www.vagrantup.com/docs/provisioning/chef_client.html</a> + </p> +</div> diff --git a/devdocs/vagrant/provisioning%2Fchef_common.html b/devdocs/vagrant/provisioning%2Fchef_common.html new file mode 100644 index 00000000..5acd1f15 --- /dev/null +++ b/devdocs/vagrant/provisioning%2Fchef_common.html @@ -0,0 +1,33 @@ +<h1 id="shared-chef-options"> Shared Chef Options </h1> <h2 id="all-chef-provisioners"> All Chef Provisioners </h2> <p>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.</p> <ul> <li> +<p><a href="#binary_path"><code>binary_path</code></a> (string) - The path to Chef's <code>bin/</code> directory on the guest machine.</p> </li> <li> +<p><a href="#binary_env"><code>binary_env</code></a> (string) - Arbitrary environment variables to set before running the Chef provisioner command. This should be of the format <code>KEY=value</code> as a string.</p> </li> <li> +<p><a href="#install"><code>install</code></a> (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):</p> <ul> <li> +<a href="#true"><code>true</code></a> (boolean) - install Chef </li> <li> +<a href="#false"><code>false</code></a> (boolean) - do not install Chef </li> <li> +<a href="#quot-force-quot-"><code>"force"</code></a> (string) - install Chef, even if it is already installed at the proper version on the guest </li> </ul> </li> <li> +<p><a href="#installer_download_path"><code>installer_download_path</code></a> (string) - The path where the Chef installer will be downloaded to. This option is only honored if the <code>install</code> attribute is <code>true</code> or <code>"force"</code>. 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.</p> </li> <li> +<p><a href="#log_level"><code>log_level</code></a> (string) - The Chef log level. See the Chef docs for acceptable values.</p> </li> <li> +<p><a href="#product"><code>product</code></a> (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.</p> </li> <li> +<p><a href="#channel"><code>channel</code></a> (string) - The release channel from which to pull the Chef Client or the Chef Development Kit. The default value is <code>"stable"</code> 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.</p> </li> <li> +<p><a href="#version"><code>version</code></a> (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 <a href="#install"><code>install</code></a> option to "force".</p> </li> <li> +<p><a href="#omnibus_url"><code>omnibus_url</code></a> (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 <a href="https://omnitruck.chef.io">https://omnitruck.chef.io</a>. The full URL is in this case:</p> <ul> <li>Linux/Unix: <a href="https://omnitruck.chef.io/install.sh">https://omnitruck.chef.io/install.sh</a> </li> <li>Windows: <a href="https://omnitruck.chef.io/install.ps1">https://omnitruck.chef.io/install.ps1</a> </li> </ul> </li> </ul> <p>If you want to have <a href="https://example.com/install.sh">https://example.com/install.sh</a> as Omnibus script for your Linux/Unix installations, you should set this option to <a href="https://example.com">https://example.com</a></p> <h2 id="runner-chef-provisioners"> Runner Chef Provisioners </h2> <p>The following options are available to any of the Chef "runner" provisioners which include <a href="chef_solo">Chef Solo</a>, <a href="chef_zero">Chef Zero</a>, and <a href="chef_client">Chef Client</a>.</p> <ul> <li> +<p><a href="#arguments"><code>arguments</code></a> (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.</p> </li> <li> +<p><a href="#attempts"><code>attempts</code></a> (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.</p> </li> <li> +<p><a href="#custom_config_path"><code>custom_config_path</code></a> (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 <em>after</em> 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.</p> </li> <li> +<p><a href="#encrypted_data_bag_secret_key_path"><code>encrypted_data_bag_secret_key_path</code></a> (string) - The path to the secret key file to decrypt encrypted data bags. By default, this is not set.</p> </li> <li> +<p><a href="#environment"><code>environment</code></a> (string) - The environment you want the Chef run to be a part of.</p> </li> <li> +<p><a href="#formatter"><code>formatter</code></a> (string) - The formatter to use for output from Chef.</p> </li> <li> +<p><a href="#http_proxy"><code>http_proxy</code></a>, <code>http_proxy_user</code>, <code>http_proxy_pass</code>, <code>no_proxy</code> (string) - Settings to configure HTTP and HTTPS proxies to use from Chef. These settings are also available with <code>http</code> replaced with <code>https</code> to configure HTTPS proxies.</p> </li> <li> +<p><a href="#json"><code>json</code></a> (hash) - Custom node attributes to pass into the Chef run.</p> </li> <li> +<p><a href="#log_level-1"><code>log_level</code></a> (string) - The log level for Chef output. This defaults to "info".</p> </li> <li> +<p><a href="#node_name"><code>node_name</code></a> (string) - The node name for the Chef Client. By default this will be your hostname.</p> </li> <li> +<p><a href="#provisioning_path"><code>provisioning_path</code></a> (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 <code>/tmp/vagrant-chef-#</code> where "#" is replaced by a unique counter.</p> </li> <li> +<p><a href="#run_list"><code>run_list</code></a> (array) - The run list that will be executed on the node.</p> </li> <li> +<p><a href="#file_cache_path"><code>file_cache_path</code></a> and <code>file_backup_path</code> (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.</p> </li> <li> +<p><a href="#verbose_logging"><code>verbose_logging</code></a> (boolean) - Whether or not to enable the Chef <code>verbose_logging</code> option. By default this is false.</p> </li> <li> +<p><a href="#enable_reporting"><code>enable_reporting</code></a> (boolean) - Whether or not to enable the Chef <code>enable_reporting</code> option. By default this is true.</p> </li> </ul><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/provisioning/chef_common.html" class="_attribution-link">https://www.vagrantup.com/docs/provisioning/chef_common.html</a> + </p> +</div> diff --git a/devdocs/vagrant/provisioning%2Fchef_solo.html b/devdocs/vagrant/provisioning%2Fchef_solo.html new file mode 100644 index 00000000..03c6e20b --- /dev/null +++ b/devdocs/vagrant/provisioning%2Fchef_solo.html @@ -0,0 +1,71 @@ +<h1 id="chef-solo-provisioner"> Chef Solo Provisioner </h1> <p><strong>Provisioner name: <code>chef_solo</code></strong></p> <p>The Vagrant Chef Solo provisioner allows you to provision the guest using <a href="https://www.chef.io/chef/">Chef</a>, specifically with <a href="https://docs.chef.io/chef_solo.html">Chef Solo</a>.</p> <p>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.</p> <blockquote class="alert alert-warning"> <p><strong>Warning:</strong> If you are not familiar with Chef and Vagrant already, I recommend starting with the <a href="shell">shell provisioner</a>. However, if you are comfortable with Vagrant already, Vagrant is the best way to learn Chef.</p> </blockquote> +<h2 id="options"> Options </h2> <p>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.</p> <ul> <li> +<p><a href="#cookbooks_path"><code>cookbooks_path</code></a> (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.</p> </li> <li> +<p><a href="#data_bags_path"><code>data_bags_path</code></a> (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.</p> </li> <li> +<p><a href="#environments_path"><code>environments_path</code></a> (string) - A path where environment definitions are located. By default, no environments folder is set.</p> </li> <li> +<p><a href="#nodes_path"><code>nodes_path</code></a> (string or array) - A list of paths where node objects (in JSON format) are stored. By default, no nodes path is set.</p> </li> <li> +<p><a href="#environment"><code>environment</code></a> (string) - The environment you want the Chef run to be a part of. This requires Chef 11.6.0 or later, and that <code>environments_path</code> is set.</p> </li> <li> +<p><a href="#recipe_url"><code>recipe_url</code></a> (string) - URL to an archive of cookbooks that Chef will download and use.</p> </li> <li> +<p><a href="#roles_path"><code>roles_path</code></a> (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.</p> </li> <li> +<p><a href="#synced_folder_type"><code>synced_folder_type</code></a> (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.</p> </li> </ul> <p>In addition to all the options listed above, the Chef Solo provisioner supports the <a href="chef_common">common options for all Chef provisioners</a>.</p> <h2 id="specifying-a-run-list"> Specifying a Run List </h2> <p>The easiest way to get started with the Chef Solo provisioner is to just specify a <a href="https://docs.chef.io/nodes.html#about-run-lists">run list</a>. This looks like:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "chef_solo" do |chef| + chef.add_recipe "apache" + end +end +</pre></div> +<p>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:</p> <div class="highlight"><pre class="highlight plaintext">$ tree +. +|-- Vagrantfile +|-- cookbooks +|  |-- apache +|  |-- recipes +|  |-- default.rb +</pre></div> +<p>The order of the calls to <code>add_recipe</code> will specify the order of the run list. Earlier recipes added with <code>add_recipe</code> are run before later recipes added.</p> <h2 id="custom-cookbooks-path"> Custom Cookbooks Path </h2> <p>Instead of using the default "cookbooks" directory, a custom cookbooks path can also be set via the <code>cookbooks_path</code> configuration directive:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "chef_solo" do |chef| + chef.cookbooks_path = "my_cookbooks" + end +end +</pre></div> +<p>The path can be relative or absolute. If it is relative, it is relative to the project root.</p> <p>The configuration value can also be an array of paths:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "chef_solo" do |chef| + chef.cookbooks_path = ["cookbooks", "my_cookbooks"] + end +end +</pre></div> +<h2 id="roles"> Roles </h2> <p>Vagrant also supports provisioning with <a href="https://docs.chef.io/roles.html">Chef roles</a>. This is done by specifying a path to a roles folder where roles are defined and by adding roles to your run list:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "chef_solo" do |chef| + chef.roles_path = "roles" + chef.add_role("web") + end +end +</pre></div> +<p>Just like the cookbooks path, the roles path is relative to the project root if a relative path is given.</p> <p>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.</p> <p><strong>Note:</strong> The name of the role file must be the same as the role name. For example the <code>web</code> role must be in the <code>roles_path</code> as web.json or web.rb. This is required by Chef itself, and is not a limitation imposed by Vagrant.</p> <h2 id="data-bags"> Data Bags </h2> <p><a href="https://docs.chef.io/data_bags.html">Data bags</a> are also supported by the Chef Solo provisioner. This is done by specifying a path to your data bags directory:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "chef_solo" do |chef| + chef.data_bags_path = "data_bags" + end +end +</pre></div> +<h2 id="custom-json-data"> Custom JSON Data </h2> <p>Additional configuration data for Chef attributes can be passed in to Chef Solo. This is done by setting the <code>json</code> property with a Ruby hash (dictionary-like object), which is converted to JSON and passed in to Chef:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "chef_solo" do |chef| + # ... + + chef.json = { + "apache" => { + "listen_address" => "0.0.0.0" + } + } + end +end +</pre></div> +<p>Hashes, arrays, etc. can be used with the JSON configuration object. Basically, anything that can be turned cleanly into JSON works.</p> <h2 id="custom-node-name"> Custom Node Name </h2> <p>You can specify a custom node name by setting the <code>node_name</code> property. This is useful for cookbooks that may depend on this being set to some sort of value. Example:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "chef_solo" do |chef| + chef.node_name = "foo" + end +end +</pre></div><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/provisioning/chef_solo.html" class="_attribution-link">https://www.vagrantup.com/docs/provisioning/chef_solo.html</a> + </p> +</div> diff --git a/devdocs/vagrant/provisioning%2Fchef_zero.html b/devdocs/vagrant/provisioning%2Fchef_zero.html new file mode 100644 index 00000000..9adb69bf --- /dev/null +++ b/devdocs/vagrant/provisioning%2Fchef_zero.html @@ -0,0 +1,29 @@ +<h1 id="chef-zero-provisioner"> Chef Zero Provisioner </h1> <p><strong>Provisioner name: <code>chef_zero</code></strong></p> <p>The Vagrant Chef Zero provisioner allows you to provision the guest using <a href="https://www.getchef.com/chef/">Chef</a>, specifically with <a href="https://docs.getchef.com/ctl_chef_client.html#run-in-local-mode">Chef Zero/local mode</a>.</p> <p>This new provisioner is a middle ground between running a full blown Chef Server and using the limited <a href="chef_solo">Chef Solo</a> provisioner. It runs a local in-memory Chef Server and fakes the validation and client key registration.</p> <blockquote class="alert alert-warning"> <p><strong>Warning:</strong> If you are not familiar with Chef and Vagrant already, I recommend starting with the <a href="shell">shell provisioner</a>. However, if you are comfortable with Vagrant already, Vagrant is the best way to learn Chef.</p> </blockquote> +<h2 id="options"> Options </h2> <p>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.</p> <ul> <li> +<p><a href="#cookbooks_path"><code>cookbooks_path</code></a> (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.</p> </li> <li> +<p><a href="#data_bags_path"><code>data_bags_path</code></a> (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.</p> </li> <li> +<p><a href="#environments_path"><code>environments_path</code></a> (string) - A path where environment definitions are located. By default, no environments folder is set.</p> </li> <li> +<p><a href="#nodes_path"><code>nodes_path</code></a> (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.</p> </li> <li> +<p><a href="#environment"><code>environment</code></a> (string) - The environment you want the Chef run to be a part of. This requires Chef 11.6.0 or later, and that <code>environments_path</code> is set.</p> </li> <li> +<p><a href="#roles_path"><code>roles_path</code></a> (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.</p> </li> <li> +<p><a href="#synced_folder_type"><code>synced_folder_type</code></a> (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.</p> </li> </ul> <p>In addition to all the options listed above, the Chef Zero provisioner supports the <a href="chef_common">common options for all Chef provisioners</a>.</p> <h2 id="usage"> Usage </h2> <p>The Chef Zero provisioner is configured basically the same way as the Chef Solo provisioner. See the <a href="chef_solo">Chef Solo documentations</a> for more information.</p> <p>A basic example could look like this:</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/provisioning/chef_zero.html" class="_attribution-link">https://www.vagrantup.com/docs/provisioning/chef_zero.html</a> + </p> +</div> diff --git a/devdocs/vagrant/provisioning%2Fdocker.html b/devdocs/vagrant/provisioning%2Fdocker.html new file mode 100644 index 00000000..7f4d00d2 --- /dev/null +++ b/devdocs/vagrant/provisioning%2Fdocker.html @@ -0,0 +1,66 @@ +<h1 id="docker-provisioner"> Docker Provisioner </h1> <p><strong>Provisioner name: <code>"docker"</code></strong></p> <p>The Vagrant Docker provisioner can automatically install <a href="https://www.docker.io">Docker</a>, pull Docker containers, and configure certain containers to run on boot.</p> <p>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.</p> <p>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.</p> <blockquote class="alert alert-info"> <p><strong>Note:</strong> This documentation is for the Docker <em>provisioner</em>. If you are looking for the Docker <em>provider</em>, visit the <a href="../docker/index">Docker provider documentation</a>.</p> </blockquote> +<h2 id="options"> Options </h2> <p>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).</p> <ul> <li> +<a href="#images"><code>images</code></a> (array) - A list of images to pull using <code>docker pull</code>. You can also use the <code>pull_images</code> function. See the example below this section for more information. </li> </ul> <p>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.</p> <ul> <li> +<p><a href="#build_image"><code>build_image</code></a> - Build an image from a Dockerfile.</p> </li> <li> +<p><a href="#pull_images"><code>pull_images</code></a> - Pull the given images. This does not start these images.</p> </li> <li> +<p><a href="#post_install_provisioner"><code>post_install_provisioner</code></a> - A <a href="../provisioning">provisioner block</a> that runs post docker installation.</p> </li> <li> +<p><a href="#run"><code>run</code></a> - Run a container and configure it to start on boot. This can only be specified once.</p> </li> </ul> <h2 id="building-images"> Building Images </h2> <p>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:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "docker" do |d| + d.build_image "/vagrant/app" + end +end +</pre></div> +<p>The argument to build an image is the path to give to <code>docker build</code>. 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.</p> <p>The <code>build_image</code> function accepts options as a second parameter. Here are the available options:</p> <ul> <li> +<a href="#args"><code>args</code></a> (string) - Additional arguments to pass to <code>docker build</code>. Use this to pass in things like <code>-t "foo"</code> to tag the image. </li> </ul> <h2 id="pulling-images"> Pulling Images </h2> <p>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 <code>images</code>:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "docker", + images: ["ubuntu"] +end +</pre></div> +<p>This will cause Vagrant to pull the "ubuntu" image from the registry for you automatically.</p> <p>The second way to pull images is to use the <code>pull_images</code> function. Each call to <code>pull_images</code> will <em>append</em> the images to be pulled. The <code>images</code> variable, on the other hand, can only be used once.</p> <p>Additionally, the <code>pull_images</code> function cannot be used with the simple configuration method for provisioners (specifying it all in one line).</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "docker" do |d| + d.pull_images "ubuntu" + d.pull_images "vagrant" + end +end +</pre></div> +<h2 id="running-containers"> Running Containers </h2> <p>In addition to pulling images, the Docker provisioner can run and start containers for you. This lets you automatically start services as part of <code>vagrant up</code>.</p> <p>Running containers can only be configured using the Ruby block syntax with the <code>do...end</code> blocks. An example of running a container is shown below:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "docker" do |d| + d.run "rabbitmq" + end +end +</pre></div> +<p>This will <code>docker run</code> 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 <code>run</code> definition. Therefore, if you need to run multiple containers from the same image then you must specify the <code>image</code> option (documented below) with a unique name.</p> <p>In addition to the name, the <code>run</code> method accepts a set of options, all optional:</p> <ul> <li> +<p><a href="#image"><code>image</code></a> (string) - The image to run. This defaults to the first argument but can also be given here as an option.</p> </li> <li> +<p><a href="#cmd"><code>cmd</code></a> (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 <a href="https:/docs.docker.io/en/latest/use/builder/#cmd">specified in the <code>Dockerfile</code></a>.</p> </li> <li> +<p><a href="#args-1"><code>args</code></a> (string) - Extra arguments for <a href="https:/docs.docker.io/en/latest/commandline/cli/#run"><code>docker run</code></a> on the command line. These are raw arguments that are passed directly to Docker.</p> </li> <li> +<p><a href="#auto_assign_name"><code>auto_assign_name</code></a> (boolean) - If true, the <code>--name</code> 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 <code>d.run "foo/bar"</code>, then the name of the container will be "foo-bar".</p> </li> <li> +<p><a href="#daemonize"><code>daemonize</code></a> (boolean) - If true, the "-d" flag is given to <code>docker run</code> to daemonize the containers. By default this is true.</p> </li> <li> +<p><a href="#restart"><code>restart</code></a> (string) - The restart policy for the container. Defaults to "always"</p> </li> </ul> <p>For example, here is how you would configure Docker to run a container with the Vagrant shared directory mounted inside of it:</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<p>In case you need to run multiple containers based off the same image, you can do so by providing different names and specifying the <code>image</code> parameter to it:</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<h2 id="other"> Other </h2> <p>This section documents some other things related to the Docker provisioner that are generally useful to know if you are using this provisioner.</p> <h3 id="customize-etc-default-docker"> Customize <code>/etc/default/docker</code> </h3> <p>To customize this file, use the <code>post_install_provisioner</code> shell provisioner.</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/provisioning/docker.html" class="_attribution-link">https://www.vagrantup.com/docs/provisioning/docker.html</a> + </p> +</div> diff --git a/devdocs/vagrant/provisioning%2Ffile.html b/devdocs/vagrant/provisioning%2Ffile.html new file mode 100644 index 00000000..10cce357 --- /dev/null +++ b/devdocs/vagrant/provisioning%2Ffile.html @@ -0,0 +1,53 @@ +<h1 id="file-provisioner"> File Provisioner </h1> <p><strong>Provisioner name: <code>"file"</code></strong></p> <p>The Vagrant file provisioner allows you to upload a file or directory from the host machine to the guest machine.</p> <p>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 <code>git config --global</code> every time you provision a new VM.</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + # ... other configuration + + config.vm.provision "file", source: "~/.gitconfig", destination: ".gitconfig" +end +</pre></div> +<p>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 <code>folder</code> as <code>newfolder</code> 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.</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + # ... other configuration + + config.vm.provision "file", source: "~/path/to/host/folder", destination: "$HOME/remote/newfolder" +end +</pre></div> +<p>Prior to copying <code>~/path/to/host/folder</code> to the guest machine:</p> <div class="highlight"><pre class="highlight plaintext"> folder + ├── script.sh + ├── otherfolder + │  └── hello.sh + ├── goodbye.sh + ├── hello.sh + └── woot.sh + + 1 directory, 5 files +</pre></div> +<p>After to copying <code>~/path/to/host/folder</code> into <code>$HOME/remote/newfolder</code> to the guest machine:</p> <div class="highlight"><pre class="highlight plaintext"> newfolder + ├── script.sh + ├── otherfolder + │  └── hello.sh + ├── goodbye.sh + ├── hello.sh + └── woot.sh + + 1 directory, 5 files +</pre></div> +<p>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.</p> <p>The file uploads by the file provisioner are done as the <em>SSH or PowerShell user</em>. 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 <a href="shell">shell provisioner</a> to move them into place.</p> <h2 id="options"> Options </h2> <p>The file provisioner takes only two options, both of which are required:</p> <ul> <li> +<p><a href="#source"><code>source</code></a> (string) - Is the local path of the file or directory to be uploaded.</p> </li> <li> +<p><a href="#destination"><code>destination</code></a> (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 <code>vagrant ssh-config</code>, and defaults to "vagrant".</p> </li> </ul> <h2 id="caveats"> Caveats </h2> <p>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:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.provision "file", source: "~/pathfolder", destination: "/remote/newlocation/" +</pre></div> +<p>You are telling vagrant to upload <code>~/pathfolder</code> under the remote dir <code>/remote/newlocation</code>, which will look like:</p> <div class="highlight"><pre class="highlight plaintext"> newlocation + ├── pathfolder + │  └── file.sh + + 1 directory, 2 files +</pre></div> +<p>This behavior can also be achieved by defining your file provisioner below:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.provision "file", source: "~/pathfolder", destination: "/remote/newlocation/pathfolder" +</pre></div> +<p>Another example is using globing on the host machine to grab all files within a folder, but not the top level folder itself:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.provision "file", source: "~/otherfolder/.", destination: "/remote/otherlocation" +</pre></div> +<p>The file provisioner is defined to include all files under <code>~/otherfolder</code> to the new location <code>/remote/otherlocation</code>. This idea can be achieved by simply having your destination folder differ from the source folder:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.provision "file", source: "/otherfolder", destination: "/remote/otherlocation" +</pre></div><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/provisioning/file.html" class="_attribution-link">https://www.vagrantup.com/docs/provisioning/file.html</a> + </p> +</div> diff --git a/devdocs/vagrant/provisioning%2Findex.html b/devdocs/vagrant/provisioning%2Findex.html new file mode 100644 index 00000000..8dbec953 --- /dev/null +++ b/devdocs/vagrant/provisioning%2Findex.html @@ -0,0 +1,9 @@ +<h1 id="provisioning"> Provisioning </h1> <p>Provisioners in Vagrant allow you to automatically install software, alter configurations, and more on the machine as part of the <code>vagrant up</code> process.</p> <p>This is useful since <a href="../boxes">boxes</a> typically are not built <em>perfectly</em> for your use case. Of course, if you want to just use <code>vagrant ssh</code> 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 <code>vagrant destroy</code> and <code>vagrant up</code> and have a fully ready-to-go work environment with a single command. Powerful.</p> <p>Vagrant gives you multiple options for provisioning the machine, from simple shell scripts to more complex, industry-standard configuration management systems.</p> <p>If you've never used a configuration management system before, it is recommended you start with basic <a href="shell">shell scripts</a> for provisioning.</p> <p>You can find the full list of built-in provisioners and usage of these provisioners in the navigational area to the left.</p> <h2 id="when-provisioning-happens"> When Provisioning Happens </h2> <p>Provisioning happens at certain points during the lifetime of your Vagrant environment:</p> <ul> <li> +<p>On the first <code>vagrant up</code> 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 <code>--provision</code> flag is explicitly provided.</p> </li> <li> +<p>When <code>vagrant provision</code> is used on a running environment.</p> </li> <li> +<p>When <code>vagrant reload --provision</code> is called. The <code>--provision</code> flag must be present to force provisioning.</p> </li> </ul> <p>You can also bring up your environment and explicitly <em>not</em> run provisioners by specifying <code>--no-provision</code>.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/provisioning/" class="_attribution-link">https://www.vagrantup.com/docs/provisioning/</a> + </p> +</div> diff --git a/devdocs/vagrant/provisioning%2Fpuppet_agent.html b/devdocs/vagrant/provisioning%2Fpuppet_agent.html new file mode 100644 index 00000000..629d5e30 --- /dev/null +++ b/devdocs/vagrant/provisioning%2Fpuppet_agent.html @@ -0,0 +1,31 @@ +<h1 id="puppet-agent-provisioner"> Puppet Agent Provisioner </h1> <p><strong>Provisioner name: <code>puppet_server</code></strong></p> <p>The Vagrant Puppet agent provisioner allows you to provision the guest using <a href="https://www.puppetlabs.com/puppet">Puppet</a>, specifically by calling <code>puppet agent</code>, connecting to a Puppet master, and retrieving the set of modules and manifests from there.</p> <blockquote class="alert alert-warning"> <p><strong>Warning:</strong> If you are not familiar with Puppet and Vagrant already, I recommend starting with the <a href="shell">shell provisioner</a>. However, if you are comfortable with Vagrant already, Vagrant is the best way to learn Puppet.</p> </blockquote> +<h2 id="options"> Options </h2> <p>The <code>puppet_server</code> provisioner takes various options. None are strictly required. They are listed below:</p> <ul> <li> +<p><a href="#binary_path"><code>binary_path</code></a> (string) - Path on the guest to Puppet's <code>bin/</code> directory.</p> </li> <li> +<p><a href="#client_cert_path"><code>client_cert_path</code></a> (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.</p> </li> <li> +<p><a href="#client_private_key_path"><code>client_private_key_path</code></a> (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.</p> </li> <li> +<p><a href="#facter"><code>facter</code></a> (hash) - Additional Facter facts to make available to the Puppet run.</p> </li> <li> +<p><a href="#options-1"><code>options</code></a> (string or array) - Additional command line options to pass to <code>puppet agent</code> when Puppet is ran.</p> </li> <li> +<p><a href="#puppet_node"><code>puppet_node</code></a> (string) - The name of the node. If this is not set, this will attempt to use a hostname if set via <code>config.vm.hostname</code>. Otherwise, the box name will be used.</p> </li> <li> +<p><a href="#puppet_server"><code>puppet_server</code></a> (string) - Hostname of the Puppet server. By default "puppet" will be used.</p> </li> </ul> <h2 id="specifying-the-puppet-master"> Specifying the Puppet Master </h2> <p>The quickest way to get started with the Puppet agent provisioner is to just specify the location of the Puppet master:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "puppet_server" do |puppet| + puppet.puppet_server = "puppet.example.com" + end +end +</pre></div> +<p>By default, Vagrant will look for the host named "puppet" on the local domain of the guest machine.</p> <h2 id="configuring-the-node-name"> Configuring the Node Name </h2> <p>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.</p> <p>The node name defaults to the hostname of the guest machine, but can be customized using the Vagrantfile:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "puppet_server" do |puppet| + puppet.puppet_node = "node.example.com" + end +end +</pre></div> +<h2 id="additional-options"> Additional Options </h2> <p>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:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "puppet_server" do |puppet| + puppet.options = "--verbose --debug" + end +end +</pre></div><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/provisioning/puppet_agent.html" class="_attribution-link">https://www.vagrantup.com/docs/provisioning/puppet_agent.html</a> + </p> +</div> diff --git a/devdocs/vagrant/provisioning%2Fpuppet_apply.html b/devdocs/vagrant/provisioning%2Fpuppet_apply.html new file mode 100644 index 00000000..1640e113 --- /dev/null +++ b/devdocs/vagrant/provisioning%2Fpuppet_apply.html @@ -0,0 +1,78 @@ +<h1 id="puppet-apply-provisioner"> Puppet Apply Provisioner </h1> <p><strong>Provisioner name: <code>puppet</code></strong></p> <p>The Vagrant Puppet provisioner allows you to provision the guest using <a href="https://www.puppetlabs.com/puppet">Puppet</a>, specifically by calling <code>puppet apply</code>, without a Puppet Master.</p> <blockquote class="alert alert-warning"> <p><strong>Warning:</strong> If you are not familiar with Puppet and Vagrant already, I recommend starting with the <a href="shell">shell provisioner</a>. However, if you are comfortable with Vagrant already, Vagrant is the best way to learn Puppet.</p> </blockquote> +<h2 id="options"> Options </h2> <p>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.</p> <ul> <li> +<p><a href="#binary_path"><code>binary_path</code></a> (string) - Path on the guest to Puppet's <code>bin/</code> directory.</p> </li> <li> +<p><a href="#facter"><code>facter</code></a> (hash) - A hash of data to set as available facter variables within the Puppet run.</p> </li> <li> +<p><a href="#hiera_config_path"><code>hiera_config_path</code></a> (string) - Path to the Hiera configuration on the host. Read the section below on how to use Hiera with Vagrant.</p> </li> <li> +<p><a href="#manifest_file"><code>manifest_file</code></a> (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 <code>manifests_path</code> (see below). This defaults to "default.pp"</p> </li> <li> +<p><a href="#manifests_path"><code>manifests_path</code></a> (string) - The path to the directory which contains the manifest files. This defaults to "manifests"</p> </li> <li> +<p><a href="#module_path"><code>module_path</code></a> (string or array of strings) - Path or paths, on the host, to the directory which contains Puppet modules, if any.</p> </li> <li> +<p><a href="#environment"><code>environment</code></a> (string) - Name of the Puppet environment.</p> </li> <li> +<p><a href="#environment_path"><code>environment_path</code></a> (string) - Path to the directory that contains environment files on the host disk.</p> </li> <li> +<p><a href="#environment_variables"><code>environment_variables</code></a> (hash) - A hash of string key/value pairs to be set as environment variables before the puppet apply run.</p> </li> <li> +<p><a href="#options-1"><code>options</code></a> (array of strings) - Additionally options to pass to the Puppet executable when running Puppet.</p> </li> <li> +<p><a href="#synced_folder_type"><code>synced_folder_type</code></a> (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.</p> </li> <li> +<p><a href="#synced_folder_args"><code>synced_folder_args</code></a> (array) - Arguments that are passed to the folder sync. For example ['-a', '--delete', '--exclude=fixtures'] for the rsync sync command.</p> </li> <li> +<p><a href="#temp_dir"><code>temp_dir</code></a> (string) - The directory where all the data associated with the Puppet run (manifest files, modules, etc.) will be stored on the guest machine.</p> </li> <li> +<p><a href="#working_directory"><code>working_directory</code></a> (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.</p> </li> </ul> <blockquote class="alert alert-warning" role="alert"> <p>If only <code>environment</code> and <code>environment_path</code> are specified, it will parse and use the manifest specified in the <code>environment.conf</code> file. If <code>manifests_path</code> and <code>manifest_file</code> is specified along with the environment options, the manifest from the environment will be overridden by the specified <code>manifest_file</code>. If <code>manifests_path</code> and <code>manifest_file</code> are specified without environments, the old non-environment mode will be used (which will fail on Puppet 4+).</p> </blockquote> <h2 id="bare-minimum"> Bare Minimum </h2> <p>The quickest way to get started with the Puppet provisioner is to just enable it:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "puppet" +end +</pre></div> +<blockquote class="alert alert-warning" role="alert"> <p><code>puppet</code> need to be installed in the guest vm.</p> </blockquote> <p>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.</p> <div class="highlight"><pre class="highlight plaintext">$ tree +. +|-- Vagrantfile +|-- manifests +|  |-- default.pp +</pre></div> +<h2 id="custom-manifest-settings"> Custom Manifest Settings </h2> <p>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 <code>manifests_path</code>, and the manifest file used as the entry-point with <code>manifest_file</code>:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "puppet" do |puppet| + puppet.manifests_path = "my_manifests" + puppet.manifest_file = "default.pp" + end +end +</pre></div> +<p>The path can be relative or absolute. If it is relative, it is relative to the project root.</p> <p>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:</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<p>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".</p> <h2 id="environments"> Environments </h2> <p>If you are using Puppet 4 or higher, you can provision using <a href="https://docs.puppetlabs.com/puppet/latest/reference/environments.html">Puppet Environments</a> by specifying the name of the environment and the path on the local disk to the environment files:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "puppet" do |puppet| + puppet.environment_path = "../puppet/environments" + puppet.environment = "testenv" + end +end +</pre></div> +<p>The default manifest is the environment's <code>manifests</code> directory. If the environment has an <code>environment.conf</code> 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 <code>environment.conf</code> use the Puppet variables <code>$codedir</code> or <code>$environment</code> they are resolved to the parent directory of <code>environment_path</code> and <code>environment</code> respectively.</p> <h2 id="modules"> Modules </h2> <p>Vagrant also supports provisioning with <a href="https://docs.puppetlabs.com/guides/modules.html">Puppet modules</a>. 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.</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "puppet" do |puppet| + puppet.module_path = "modules" + end +end +</pre></div> +<p>Just like the manifests path, the modules path is relative to the project root if a relative path is given.</p> <h2 id="custom-facts"> Custom Facts </h2> <p>Custom facts to be exposed by <a href="https://puppetlabs.com/facter">Facter</a> can be specified as well:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "puppet" do |puppet| + puppet.facter = { + "vagrant" => "1" + } + end +end +</pre></div> +<p>Now, the <code>$vagrant</code> variable in your Puppet manifests will equal "1".</p> <h2 id="configuring-hiera"> Configuring Hiera </h2> <p><a href="https://docs.puppetlabs.com/hiera/1/">Hiera</a> configuration is also supported. <code>hiera_config_path</code> specifies the path to the Hiera configuration file stored on the host. If the <code>:datadir</code> setting in the Hiera configuration file is a relative path, <code>working_directory</code> should be used to specify the directory in the guest that path is relative to.</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<p><code>hiera_config_path</code> can be relative or absolute. If it is relative, it is relative to the project root. <code>working_directory</code> is an absolute path within the guest.</p> <h2 id="additional-options"> Additional Options </h2> <p>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:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "puppet" do |puppet| + puppet.options = "--verbose --debug" + end +end +</pre></div><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/provisioning/puppet_apply.html" class="_attribution-link">https://www.vagrantup.com/docs/provisioning/puppet_apply.html</a> + </p> +</div> diff --git a/devdocs/vagrant/provisioning%2Fsalt.html b/devdocs/vagrant/provisioning%2Fsalt.html new file mode 100644 index 00000000..7d16bad3 --- /dev/null +++ b/devdocs/vagrant/provisioning%2Fsalt.html @@ -0,0 +1,75 @@ +<h1 id="salt-provisioner"> Salt Provisioner </h1> <p><strong>Provisioner name: <code>salt</code></strong></p> <p>The Vagrant Salt provisioner allows you to provision the guest using <a href="http://saltstack.com/">Salt</a> states.</p> <p>Salt states are <a href="https://en.wikipedia.org/wiki/YAML">YAML</a> 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.</p> <p><em>NOTE: The Salt provisioner is builtin to Vagrant. If the <code>vagrant-salt</code> plugin is installed, it should be uninstalled to ensure expected behavior.</em></p> <h2 id="masterless-quickstart"> Masterless Quickstart </h2> <p>What follows is a basic Vagrantfile that will get salt working on a single minion, without a master:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby"> Vagrant.configure("2") do |config| + ## Choose your base box + config.vm.box = "precise64" + + ## 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 +</pre></div> +<p>This sets up a shared folder for the salt root, and copies the minion file over, then runs <code>state.highstate</code> on the machine. Your minion file must contain the line <code>file_client: local</code> in order to work in a masterless setup.</p> <h2 id="install-options"> Install Options </h2> <ul> <li> +<p><a href="#install_master"><code>install_master</code></a> (boolean) - Should vagrant install the salt-master on this machine. Not supported on Windows guest machines.</p> </li> <li> +<p><a href="#no_minion"><code>no_minion</code></a> (boolean) - Do not install the minion, default <code>false</code>. Not supported on Windows guest machines.</p> </li> <li> +<p><a href="#install_syndic"><code>install_syndic</code></a> (boolean) - Install the salt-syndic, default <code>false</code>. Not supported on Windows guest machines.</p> </li> <li> +<p><a href="#install_type"><code>install_type</code></a> (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.</p> </li> <li> +<p><a href="#install_args"><code>install_args</code></a> (string, default: "develop") - When performing a git install, you can specify a branch, tag, or any treeish. Not supported on Windows.</p> </li> <li> +<p><a href="#always_install"><code>always_install</code></a> (boolean) - Installs salt binaries even if they are already detected, default <code>false</code></p> </li> <li> +<p><a href="#bootstrap_script"><code>bootstrap_script</code></a> (string) - Path to your customized salt-bootstrap.sh script. Not supported on Windows guest machines.</p> </li> <li> +<p><a href="#bootstrap_options"><code>bootstrap_options</code></a> (string) - Additional command-line options to pass to the bootstrap script.</p> </li> <li> +<p><a href="#version"><code>version</code></a> (string, default: "2017.7.1") - Version of minion to be installed.</p> </li> <li> +<p><a href="#python_version"><code>python_version</code></a> (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.</p> </li> </ul> <h2 id="minion-options"> Minion Options </h2> <p>These only make sense when <code>no_minion</code> is <code>false</code>.</p> <ul> <li> +<p><a href="#minion_config"><code>minion_config</code></a> (string, default: "salt/minion") - Path to a custom salt minion config file.</p> </li> <li> +<p><a href="#minion_key"><code>minion_key</code></a> (string, default: "salt/key/minion.key") - Path to your minion key</p> </li> <li> +<p><a href="#minion_id"><code>minion_id</code></a> (string) - Unique identifier for minion. Used for masterless and preseeding keys.</p> </li> <li> +<p><a href="#minion_pub"><code>minion_pub</code></a> (string, default: "salt/key/minion.pub") - Path to your minion public key</p> </li> <li> +<p><a href="#grains_config"><code>grains_config</code></a> (string) - Path to a custom salt grains file. On Windows, the minion needs <code>ipc_mode: tcp</code> set otherwise it will <a href="https://github.com/saltstack/salt/issues/22796">fail to communicate</a> with the master.</p> </li> <li> +<p><a href="#masterless"><code>masterless</code></a> (boolean) - Calls state.highstate in local mode. Uses <code>minion_id</code> and <code>pillar_data</code> when provided.</p> </li> <li> +<p><a href="#minion_json_config"><code>minion_json_config</code></a> (string) - Valid json for configuring the salt minion (<code>-j</code> in bootstrap-salt.sh). Not supported on Windows.</p> </li> <li> +<p><a href="#salt_call_args"><code>salt_call_args</code></a> (array) - An array of additional command line flag arguments to be passed to the <code>salt-call</code> command when provisioning with masterless.</p> </li> </ul> <h2 id="master-options"> Master Options </h2> <p>These only make sense when <code>install_master</code> is <code>true</code>. Not supported on Windows guest machines.</p> <ul> <li> +<p><a href="#master_config"><code>master_config</code></a> (string, default: "salt/master") Path to a custom salt master config file.</p> </li> <li> +<p><a href="#master_key"><code>master_key</code></a> (string, default: "salt/key/master.pem") - Path to your master key.</p> </li> <li> +<p><a href="#master_pub"><code>master_pub</code></a> (string, default: "salt/key/master.pub") - Path to your master public key.</p> </li> <li> +<p><a href="#seed_master"><code>seed_master</code></a> (dictionary) - Upload keys to master, thereby pre-seeding it before use. Example: <code>{minion_name:/path/to/key.pub}</code></p> </li> <li> +<p><a href="#master_json_config"><code>master_json_config</code></a> (string) - Valid json for configuring the salt master (<code>-J</code> in bootstrap-salt.sh). Not supported on Windows.</p> </li> <li> +<p><a href="#salt_args"><code>salt_args</code></a> (array) - An array of additional command line flag arguments to be passed to the <code>salt</code> command when provisioning with masterless.</p> </li> </ul> <h2 id="execute-states"> Execute States </h2> <p>Either of the following may be used to actually execute states during provisioning.</p> <ul> <li> +<a href="#run_highstate"><code>run_highstate</code></a> - (boolean) Executes <code>state.highstate</code> on vagrant up. Can be applied to any machine. </li> </ul> <h2 id="execute-runners"> Execute Runners </h2> <p>Either of the following may be used to actually execute runners during provisioning.</p> <ul> <li> +<p><a href="#run_overstate"><code>run_overstate</code></a> - (boolean) Executes <code>state.over</code> on vagrant up. Can be applied to the master only. This is superseded by orchestrate. Not supported on Windows guest machines.</p> </li> <li> +<p><a href="#orchestrations"><code>orchestrations</code></a> - (array of strings) Executes <code>state.orchestrate</code> on vagrant up. Can be applied to the master only. This is superseded by run_overstate. Not supported on Windows guest machines.</p> </li> </ul> <h2 id="output-control"> Output Control </h2> <p>These may be used to control the output of state execution:</p> <ul> <li> +<p><a href="#colorize"><code>colorize</code></a> (boolean) - If true, output is colorized. Defaults to false.</p> </li> <li> +<p><a href="#log_level"><code>log_level</code></a> (string) - The verbosity of the outputs. Defaults to "debug". Can be one of "all", "garbage", "trace", "debug", "info", or "warning". Requires <code>verbose</code> to be set to "true".</p> </li> <li> +<p><a href="#verbose"><code>verbose</code></a> (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.</p> </li> </ul> <h2 id="pillar-data"> Pillar Data </h2> <p>You can export pillar data for use during provisioning by using the <code>pillar</code> 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::</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<p>On Windows guests, this requires PowerShell 3.0 or higher.</p> <h2 id="preseeding-keys"> Preseeding Keys </h2> <p>Preseeding keys is the recommended way to handle provisioning using a master. On a machine with salt installed, run <code>salt-key --gen-keys=[minion_id]</code> to generate the necessary .pub and .pem files</p> <p>For an example of a more advanced setup, look at the original <a href="https://github.com/saltstack/salty-vagrant/tree/develop/example">plugin</a>.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/provisioning/salt.html" class="_attribution-link">https://www.vagrantup.com/docs/provisioning/salt.html</a> + </p> +</div> diff --git a/devdocs/vagrant/provisioning%2Fshell.html b/devdocs/vagrant/provisioning%2Fshell.html new file mode 100644 index 00000000..0b8112e5 --- /dev/null +++ b/devdocs/vagrant/provisioning%2Fshell.html @@ -0,0 +1,60 @@ +<h1 id="shell-provisioner"> Shell Provisioner </h1> <p><strong>Provisioner name: <code>"shell"</code></strong></p> <p>The Vagrant Shell provisioner allows you to upload and execute a script within the guest machine.</p> <p>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.</p> <p>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.</p> <h2 id="options"> Options </h2> <p>The shell provisioner takes various options. One of <code>inline</code> or <code>path</code> is required:</p> <ul> <li> +<p><a href="#inline"><code>inline</code></a> (string) - Specifies a shell command inline to execute on the remote machine. See the <a href="#inline-scripts">inline scripts</a> section below for more information.</p> </li> <li> +<p><a href="#path"><code>path</code></a> (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 <a href="https://gist.github.com">gist</a>).</p> </li> </ul> <p>The remainder of the available options are optional:</p> <ul> <li> +<p><a href="#args"><code>args</code></a> (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.</p> </li> <li> +<p><a href="#env"><code>env</code></a> (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.</p> </li> <li> +<p><a href="#binary"><code>binary</code></a> (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".</p> </li> <li> +<p><a href="#privileged"><code>privileged</code></a> (boolean) - Specifies whether to execute the shell script as a privileged user or not (<code>sudo</code>). By default this is "true". Windows guests use a scheduled task to run as a true administrator without the WinRM limitations.</p> </li> <li> +<p><a href="#upload_path"><code>upload_path</code></a> (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".</p> </li> <li> +<p><a href="#keep_color"><code>keep_color</code></a> (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.</p> </li> <li> +<p><a href="#name"><code>name</code></a> (string) - This value will be displayed in the output so that identification by the user is easier when many shell provisioners are present.</p> </li> <li> +<p><a href="#powershell_args"><code>powershell_args</code></a> (string) - Extra arguments to pass to <code>PowerShell</code> if you are provisioning with PowerShell on Windows.</p> </li> <li> +<p><a href="#powershell_elevated_interactive"><code>powershell_elevated_interactive</code></a> (boolean) - Run an elevated script in interactive mode on Windows. By default this is "false". Must also be <code>privileged</code>. Be sure to enable auto-login for Windows as the user must be logged in for interactive mode to work.</p> </li> <li> +<p><a href="#md5"><code>md5</code></a> (string) - MD5 checksum used to validate remotely downloaded shell files.</p> </li> <li> +<p><a href="#sha1"><code>sha1</code></a> (string) - SHA1 checksum used to validate remotely downloaded shell files.</p> </li> <li> +<p><a href="#sensitive"><code>sensitive</code></a> (boolean) - Marks the Hash values used in the <code>env</code> option as sensitive and hides them from output. By default this is "false".</p> </li> </ul> <h2 id="inline-scripts"> Inline Scripts </h2> <p>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:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "shell", + inline: "echo Hello, World" +end +</pre></div> +<p>This causes <code>echo Hello, World</code> to be run within the guest machine when provisioners are run.</p> <p>Combined with a little bit more Ruby, this makes it very easy to embed your shell scripts directly within your Vagrantfile. Another example below:</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<p>I understand 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 <code>$script</code>. This global variable contains a string which is then passed in as the inline script to the Vagrant configuration.</p> <p>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.</p> <p>For Windows guest machines, the inline script <em>must</em> be PowerShell. Batch scripts are not allowed as inline scripts.</p> <h2 id="external-script"> External Script </h2> <p>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:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "shell", path: "script.sh" +end +</pre></div> +<p>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 <code>~</code> (home directory) and <code>..</code> (parent directory).</p> <p>If you use a remote script as part of your provisioning process, you can pass in its URL as the <code>path</code> argument as well:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "shell", path: "https://example.com/provisioner.sh" +end +</pre></div> +<p>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. If you exclude this extension, it likely will not work.</p> <p>To run a script already available on the guest you can use an inline script to invoke the remote script on the guest.</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "shell", + inline: "/bin/sh /path/to/the/script/already/on/the/guest.sh" +end +</pre></div> +<h2 id="script-arguments"> Script Arguments </h2> <p>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:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "shell" do |s| + s.inline = "echo $1" + s.args = "'hello, world!'" + end +end +</pre></div> +<p>You can also specify arguments as an array if you do not want to worry about quoting:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.provision "shell" do |s| + s.inline = "echo $1" + s.args = ["hello, world!"] + end +end +</pre></div><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/provisioning/shell.html" class="_attribution-link">https://www.vagrantup.com/docs/provisioning/shell.html</a> + </p> +</div> diff --git a/devdocs/vagrant/provisioning.html b/devdocs/vagrant/provisioning.html new file mode 100644 index 00000000..5af6b759 --- /dev/null +++ b/devdocs/vagrant/provisioning.html @@ -0,0 +1,9 @@ +<h1 id="provisioning"> Provisioning </h1> <p>Provisioners in Vagrant allow you to automatically install software, alter configurations, and more on the machine as part of the <code>vagrant up</code> process.</p> <p>This is useful since <a href="boxes">boxes</a> typically are not built <em>perfectly</em> for your use case. Of course, if you want to just use <code>vagrant ssh</code> 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 <code>vagrant destroy</code> and <code>vagrant up</code> and have a fully ready-to-go work environment with a single command. Powerful.</p> <p>Vagrant gives you multiple options for provisioning the machine, from simple shell scripts to more complex, industry-standard configuration management systems.</p> <p>If you've never used a configuration management system before, it is recommended you start with basic <a href="provisioning/shell">shell scripts</a> for provisioning.</p> <p>You can find the full list of built-in provisioners and usage of these provisioners in the navigational area to the left.</p> <h2 id="when-provisioning-happens"> When Provisioning Happens </h2> <p>Provisioning happens at certain points during the lifetime of your Vagrant environment:</p> <ul> <li> +<p>On the first <code>vagrant up</code> 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 <code>--provision</code> flag is explicitly provided.</p> </li> <li> +<p>When <code>vagrant provision</code> is used on a running environment.</p> </li> <li> +<p>When <code>vagrant reload --provision</code> is called. The <code>--provision</code> flag must be present to force provisioning.</p> </li> </ul> <p>You can also bring up your environment and explicitly <em>not</em> run provisioners by specifying <code>--no-provision</code>.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/provisioning" class="_attribution-link">https://www.vagrantup.com/docs/provisioning</a> + </p> +</div> diff --git a/devdocs/vagrant/push%2Fftp.html b/devdocs/vagrant/push%2Fftp.html new file mode 100644 index 00000000..06db78b1 --- /dev/null +++ b/devdocs/vagrant/push%2Fftp.html @@ -0,0 +1,22 @@ +<h1 id="vagrant-push"> Vagrant Push </h1> <h2 id="ftp-amp-sftp-strategy"> FTP & SFTP Strategy </h2> <p>Vagrant Push FTP and SFTP strategy pushes the code in your Vagrant development environment to a remote FTP or SFTP server.</p> <p>The Vagrant Push FTP And SFTP strategy supports the following configuration options:</p> <ul> <li> +<p><a href="#host"><code>host</code></a> - 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 (<code>host:port</code>).</p> </li> <li> +<p><a href="#username"><code>username</code></a> - The username to use for authentication with the (S)FTP server.</p> </li> <li> +<p><a href="#password"><code>password</code></a> - The password to use for authentication with the (S)FTP server.</p> </li> <li> +<p><a href="#passive"><code>passive</code></a> - Use passive FTP (default is true).</p> </li> <li> +<p><a href="#secure"><code>secure</code></a> - Use secure (SFTP) (default is false).</p> </li> <li> +<p><a href="#destination"><code>destination</code></a> - The root destination on the target system to sync the files (default is <code>/</code>).</p> </li> <li> +<p><a href="#exclude"><code>exclude</code></a> - Add a file or file pattern to exclude from the upload, relative to the <code>dir</code>. This value may be specified multiple times and is additive. <code>exclude</code> take precedence over <code>include</code> values.</p> </li> <li> +<p><a href="#include"><code>include</code></a> - Add a file or file pattern to include in the upload, relative to the <code>dir</code>. This value may be specified multiple times and is additive.</p> </li> <li> +<p><a href="#dir"><code>dir</code></a> - 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 <code>src</code> folder or <code>bin</code> folder or some other folder you want to upload.</p> </li> </ul> <h3 id="usage"> Usage </h3> <p>The Vagrant Push FTP and SFTP strategy is defined in the <code>Vagrantfile</code> using the <code>ftp</code> key:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.push.define "ftp" do |push| + push.host = "ftp.company.com" + push.username = "username" + push.password = "password" +end +</pre></div> +<p>And then push the application to the FTP or SFTP server:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ vagrant push +</pre></div><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/push/ftp.html" class="_attribution-link">https://www.vagrantup.com/docs/push/ftp.html</a> + </p> +</div> diff --git a/devdocs/vagrant/push%2Fheroku.html b/devdocs/vagrant/push%2Fheroku.html new file mode 100644 index 00000000..e9468d84 --- /dev/null +++ b/devdocs/vagrant/push%2Fheroku.html @@ -0,0 +1,15 @@ +<h1 id="vagrant-push"> Vagrant Push </h1> <h2 id="heroku-strategy"> Heroku Strategy </h2> <p><a href="https://heroku.com/" title="Heroku">Heroku</a> 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.</p> <blockquote class="alert alert-warning"> <p><strong>Warning:</strong> 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 <a href="https://devcenter.heroku.com">Heroku documentation</a>.</p> </blockquote> +<p>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.</p> <p>The Vagrant Push Heroku strategy supports the following configuration options:</p> <ul> <li> +<p><a href="#app"><code>app</code></a> - 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 <code>Vagrantfile</code> 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 <code>app</code> setting to your <code>Vagrantfile</code>.</p> </li> <li> +<p><a href="#dir"><code>dir</code></a> - 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.</p> </li> <li> +<p><a href="#remote"><code>remote</code></a> - The name of the Git remote where Heroku is configured. The default value is "heroku".</p> </li> </ul> <h3 id="usage"> Usage </h3> <p>The Vagrant Push Heroku strategy is defined in the <code>Vagrantfile</code> using the <code>heroku</code> key:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.push.define "heroku" do |push| + push.app = "my_application" +end +</pre></div> +<p>And then push the application to Heroku:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ vagrant push +</pre></div><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/push/heroku.html" class="_attribution-link">https://www.vagrantup.com/docs/push/heroku.html</a> + </p> +</div> diff --git a/devdocs/vagrant/push%2Findex.html b/devdocs/vagrant/push%2Findex.html new file mode 100644 index 00000000..86aa70fd --- /dev/null +++ b/devdocs/vagrant/push%2Findex.html @@ -0,0 +1,24 @@ +<h1 id="vagrant-push"> Vagrant Push </h1> <p>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.</p> <p>Pushes are defined in an application's <code>Vagrantfile</code> and are invoked using the <code>vagrant push</code> 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 <code>Vagrantfile</code>:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.push.define "ftp" do |push| + push.host = "ftp.company.com" + push.username = "..." + # ... +end +</pre></div> +<p>When the application is ready to be deployed to the FTP server, just run a single command:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ vagrant push +</pre></div> +<p>Much like <a href="../providers/index" title="Vagrant Providers">Vagrant Providers</a>, Vagrant Push also supports multiple backend declarations. Consider the common scenario of a staging and QA environment:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.push.define "staging", strategy: "ftp" do |push| + # ... +end + +config.push.define "qa", strategy: "ftp" do |push| + # ... +end +</pre></div> +<p>In this scenario, the user must pass the name of the Vagrant Push to the subcommand:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ vagrant push staging +</pre></div> +<p>Vagrant Push is the easiest way to deploy your application. You can read more in the documentation links on the sidebar.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/push/" class="_attribution-link">https://www.vagrantup.com/docs/push/</a> + </p> +</div> diff --git a/devdocs/vagrant/push%2Flocal-exec.html b/devdocs/vagrant/push%2Flocal-exec.html new file mode 100644 index 00000000..e9df2f6f --- /dev/null +++ b/devdocs/vagrant/push%2Flocal-exec.html @@ -0,0 +1,28 @@ +<h1 id="vagrant-push"> Vagrant Push </h1> <h2 id="local-exec-strategy"> Local Exec Strategy </h2> <p>The Vagrant Push Local Exec strategy allows the user to invoke an arbitrary shell command or script as part of a push.</p> <blockquote class="alert alert-warning"> <p><strong>Warning:</strong> The Vagrant Push Local Exec strategy does not perform any validation on the correctness of the shell script.</p> </blockquote> +<p>The Vagrant Push Local Exec strategy supports the following configuration options:</p> <ul> <li> +<a href="#script"><code>script</code></a> - The path to a script on disk (relative to the <code>Vagrantfile</code>) to execute. Vagrant will attempt to convert this script to an executable, but an exception will be raised if that fails. </li> <li> +<a href="#inline"><code>inline</code></a> - The inline script to execute (as a string). </li> <li> +<a href="#args"><code>args</code></a> (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. </li> </ul> <p>Please note - only one of the <code>script</code> and <code>inline</code> options may be specified in a single push definition.</p> <h3 id="usage"> Usage </h3> <p>The Vagrant Push Local Exec strategy is defined in the <code>Vagrantfile</code> using the <code>local-exec</code> key:</p> <p>Remote path:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.push.define "local-exec" do |push| + push.inline = <<-SCRIPT + scp -r . server:/var/www/website + SCRIPT +end +</pre></div> +<p>Local path:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.push.define "local-exec" do |push| + push.inline = <<-SCRIPT + cp -r . /var/www/website + SCRIPT +end +</pre></div> +<p>For more complicated scripts, you may store them in a separate file and read them from the <code>Vagrantfile</code> like so:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.push.define "local-exec" do |push| + push.script = "my-script.sh" +end +</pre></div> +<p>And then invoke the push with Vagrant:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ vagrant push +</pre></div> +<h3 id="script-arguments"> Script Arguments </h3> <p>Refer to <a href="../provisioning/shell">Shell Provisioner</a>.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/push/local-exec.html" class="_attribution-link">https://www.vagrantup.com/docs/push/local-exec.html</a> + </p> +</div> diff --git a/devdocs/vagrant/share%2Fconnect.html b/devdocs/vagrant/share%2Fconnect.html new file mode 100644 index 00000000..6fb882d5 --- /dev/null +++ b/devdocs/vagrant/share%2Fconnect.html @@ -0,0 +1,6 @@ +<h1 id="vagrant-connect"> Vagrant Connect </h1> <p>Vagrant can share any or <em>every</em> port to your Vagrant environment, not just SSH and HTTP. The <code>vagrant connect</code> 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.</p> <h2 id="usage"> Usage </h2> <p>Just call <code>vagrant share --full</code>. This will automatically share as many ports as possible for remote connections. Please see <a href="security">the Vagrant share security page</a> for more information.</p> <p>Note the share name at the end of calling <code>vagrant share --full</code>, and give this to the person who wants to connect to your machine. They simply have to call <code>vagrant connect NAME</code>. This will give them a static IP they can use to access your Vagrant environment.</p> <h2 id="how-does-it-work-"> How does it work? </h2> <p><code>vagrant connect</code> works by doing what Vagrant does best: managing virtual machines. <code>vagrant connect</code> creates a tiny virtual machine that takes up only around 20 MB in RAM, using VirtualBox or VMware (more provider support is coming soon).</p> <p>Any traffic sent to this tiny virtual machine is then proxied through to the shared Vagrant environment as if it were directed at it.</p> <h2 id="beware-vagrant-insecure-key"> Beware: Vagrant Insecure Key </h2> <p>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.</p> <p>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.</p> <p>In this case, we recommend changing or removing the insecure key from the Vagrant machine.</p> <p>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.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/share/connect.html" class="_attribution-link">https://www.vagrantup.com/docs/share/connect.html</a> + </p> +</div> diff --git a/devdocs/vagrant/share%2Fhttp.html b/devdocs/vagrant/share%2Fhttp.html new file mode 100644 index 00000000..da7c50b7 --- /dev/null +++ b/devdocs/vagrant/share%2Fhttp.html @@ -0,0 +1,15 @@ +<h1 id="http-sharing"> HTTP Sharing </h1> <p>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 <code>vagrant share</code> is used.</p> <p>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.</p> <p>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.</p> <h2 id="usage"> Usage </h2> <p>To use HTTP sharing, simply run <code>vagrant share</code>:</p> <div class="highlight"><pre class="highlight plaintext">$ 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 +</pre></div> +<p>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!</p> <p>If Vagrant has trouble detecting the port of your servers in your environment, use the <code>--http</code> and/or <code>--https</code> flags to be more explicit.</p> <p>The share will be accessible for the duration that <code>vagrant share</code> is running. Press <code>Ctrl-C</code> to quit the sharing session.</p> <blockquote class="alert alert-warning"> <p><strong>Warning:</strong> This URL is accessible by <em>anyone</em> who knows it, so be careful if you are sharing sensitive information.</p> </blockquote> +<h2 id="disabling"> Disabling </h2> <p>If you want to disable the creation of the publicly accessible endpoint, run <code>vagrant share</code> with the <code>--disable-http</code> flag. This will share your environment using one of the other methods available, and will not create the URL endpoint.</p> <h2 id="missing-assets"> Missing Assets </h2> <p>Shared web applications must use <strong>relative paths</strong> for loading any local assets such as images, stylesheets, javascript.</p> <p>The web application under development will be accessed remotely. This means that if you have any hardcoded asset (images, stylesheets, etc.) URLs such as <code><img src="http://127.0.0.1/header.png"></code>, then they will not load for people accessing your share.</p> <p>Most web frameworks or toolkits have settings or helpers to generate relative paths. For example, if you are a WordPress developer, the <a href="http://wordpress.org/plugins/root-relative-urls/">Root Relative URLs</a> plugin will automatically do this for you.</p> <p>Relative URLs to assets is generally a best practice in general, so you should do this anyways!</p> <h2 id="https-ssl-"> HTTPS (SSL) </h2> <p>Vagrant Share can also expose an SSL port that can be accessed over SSL. Creating an HTTPS share requires a non-free ngrok account.</p> <p><code>vagrant share</code> 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.</p> <p>The HTTPS share can be explicitly disabled using the <code>--disable-https</code> flag.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/share/http.html" class="_attribution-link">https://www.vagrantup.com/docs/share/http.html</a> + </p> +</div> diff --git a/devdocs/vagrant/share%2Findex.html b/devdocs/vagrant/share%2Findex.html new file mode 100644 index 00000000..32c7b0e5 --- /dev/null +++ b/devdocs/vagrant/share%2Findex.html @@ -0,0 +1,11 @@ +<h1 id="vagrant-share"> Vagrant Share </h1> <p>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: <code>vagrant share</code>.</p> <p>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:</p> <ul> <li> +<p><strong>HTTP sharing</strong> 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.</p> </li> <li> +<p><strong>SSH sharing</strong> will allow instant SSH access to your Vagrant environment by anyone by running <code>vagrant connect --ssh</code> on the remote side. This is useful for pair programming, debugging ops problems, etc.</p> </li> <li> +<p><strong>General sharing</strong> allows anyone to access any exposed port of your Vagrant environment by running <code>vagrant connect</code> 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.</p> </li> </ul> <p>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.</p> <h2 id="installation"> Installation </h2> <p>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:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ vagrant plugin install vagrant-share +</pre></div> +<p>Vagrant Share requires <a href="https://ngrok.com">ngrok</a> to be used.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/share/" class="_attribution-link">https://www.vagrantup.com/docs/share/</a> + </p> +</div> diff --git a/devdocs/vagrant/share%2Fprovider.html b/devdocs/vagrant/share%2Fprovider.html new file mode 100644 index 00000000..d4c491d0 --- /dev/null +++ b/devdocs/vagrant/share%2Fprovider.html @@ -0,0 +1,8 @@ +<h1 id="custom-provider"> Custom Provider </h1> <blockquote class="alert alert-warning"> <p><strong>Warning: Advanced Topic!</strong> 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.</p> </blockquote> +<p>If you are developing a <a href="../plugins/providers">custom Vagrant provider</a>, you will need to do a tiny bit more work in order for it to work well with Vagrant Share.</p> <p>For now, this is only one step:</p> <ul> <li> +<a href="#public_address"><code>public_address</code></a> 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 <code>nil</code>. </li> </ul><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/share/provider.html" class="_attribution-link">https://www.vagrantup.com/docs/share/provider.html</a> + </p> +</div> diff --git a/devdocs/vagrant/share%2Fsecurity.html b/devdocs/vagrant/share%2Fsecurity.html new file mode 100644 index 00000000..9b90f755 --- /dev/null +++ b/devdocs/vagrant/share%2Fsecurity.html @@ -0,0 +1,10 @@ +<h1 id="security"> Security </h1> <p>Sharing your Vagrant environment understandably raises a number of security concerns.</p> <p>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:</p> <ul> <li> +<a href="#disable-http"><code>--disable-http</code></a> will not create a publicly accessible HTTP URL. When this is set, the only way to access the share is with <code>vagrant connect</code>. </li> </ul> <p>In addition to these options, there are other features we've built to help:</p> <ul> <li> +<p>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.</p> </li> <li> +<p>SSH keys are encrypted by default, using a password that is not transmitted to our servers or across the network at all.</p> </li> <li> +<p>SSH is not shared by default, it must explicitly be shared with the <code>--ssh</code> flag.</p> </li> </ul> <p>Most importantly, you must understand that by running <code>vagrant share</code>, you are making your Vagrant environment accessible by anyone who knows the share name. When share is not running, it is not accessible.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/share/security.html" class="_attribution-link">https://www.vagrantup.com/docs/share/security.html</a> + </p> +</div> diff --git a/devdocs/vagrant/share%2Fssh.html b/devdocs/vagrant/share%2Fssh.html new file mode 100644 index 00000000..92c6a700 --- /dev/null +++ b/devdocs/vagrant/share%2Fssh.html @@ -0,0 +1,62 @@ +<h1 id="ssh-sharing"> SSH Sharing </h1> <p>Vagrant share makes it trivially easy to allow remote SSH access to your Vagrant environment by supplying the <code>--ssh</code> flag to <code>vagrant share</code>.</p> <p>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!</p> <p>SSH sharing is disabled by default as a security measure. To enable SSH sharing, simply supply the <code>--ssh</code> flag when calling <code>vagrant share</code>.</p> <h2 id="usage"> Usage </h2> <p>Just run <code>vagrant share --ssh</code>!</p> <p>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 <em>never</em> 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.</p> <p>After running <code>vagrant share --ssh</code>, it will output the name of your share:</p> <div class="highlight"><pre class="highlight plaintext">$ 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: +</pre></div> +<p>Anyone can then SSH directly to your Vagrant environment by running <code>vagrant connect --ssh NAME</code> where NAME is the name of the share outputted previously.</p> <div class="highlight"><pre class="highlight plaintext">$ 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:~$ +</pre></div> +<p>If the private key is encrypted (the default behavior), then the connecting person will be prompted for the password to decrypt the private key.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/share/ssh.html" class="_attribution-link">https://www.vagrantup.com/docs/share/ssh.html</a> + </p> +</div> diff --git a/devdocs/vagrant/synced-folders%2Fbasic_usage.html b/devdocs/vagrant/synced-folders%2Fbasic_usage.html new file mode 100644 index 00000000..a15af212 --- /dev/null +++ b/devdocs/vagrant/synced-folders%2Fbasic_usage.html @@ -0,0 +1,31 @@ +<h1 id="basic-usage"> Basic Usage </h1> <h2 id="configuration"> Configuration </h2> <p>Synced folders are configured within your Vagrantfile using the <code>config.vm.synced_folder</code> method. Usage of the configuration directive is very simple:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + # other config here + + config.vm.synced_folder "src/", "/srv/website" +end +</pre></div> +<p>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.</p> <h2 id="options"> Options </h2> <p>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.</p> <p>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.</p> <ul> <li> +<p><a href="#create"><code>create</code></a> (boolean) - If true, the host path will be created if it does not exist. Defaults to false.</p> </li> <li> +<p><a href="#disabled"><code>disabled</code></a> (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.</p> </li> <li> +<p><a href="#group"><code>group</code></a> (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.</p> </li> <li> +<p><a href="#mount_options"><code>mount_options</code></a> (array) - A list of additional mount options to pass to the <code>mount</code> command.</p> </li> <li> +<p><a href="#owner"><code>owner</code></a> (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.</p> </li> <li> +<p><a href="#type"><code>type</code></a> (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".</p> </li> <li> +<p><a href="#id"><code>id</code></a> (string) - The name for the mount point of this synced folder in the guest machine. This shows up when you run <code>mount</code> in the guest machine.</p> </li> </ul> <h2 id="enabling"> Enabling </h2> <p>Synced folders are automatically setup during <code>vagrant up</code> and <code>vagrant reload</code>.</p> <h2 id="disabling"> Disabling </h2> <p>Synced folders can be disabled by adding the <code>disabled</code> option to any definition:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.synced_folder "src/", "/srv/website", disabled: true +end +</pre></div> +<p>Disabling the default <code>/vagrant</code> share can be done as follows:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.synced_folder ".", "/vagrant", disabled: true +</pre></div> +<h2 id="modifying-the-owner-group"> Modifying the Owner/Group </h2> <p>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:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.synced_folder "src/", "/srv/website", + owner: "root", group: "root" +</pre></div> +<p><em>NOTE: Owner and group IDs defined within <code>mount_options</code> will have precedence over the <code>owner</code> and <code>group</code> options.</em></p> <p>For example, given the following configuration:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.synced_folder ".", "/vagrant", owner: "vagrant", + group: "vagrant", mount_options: ["uid=1234", "gid=1234"] +</pre></div> +<p>the mounted synced folder will be owned by the user with ID <code>1234</code> and the group with ID <code>1234</code>. The <code>owner</code> and <code>group</code> options will be ignored.</p> <h2 id="symbolic-links"> Symbolic Links </h2> <p>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.</p> <p>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.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/synced-folders/basic_usage.html" class="_attribution-link">https://www.vagrantup.com/docs/synced-folders/basic_usage.html</a> + </p> +</div> diff --git a/devdocs/vagrant/synced-folders%2Findex.html b/devdocs/vagrant/synced-folders%2Findex.html new file mode 100644 index 00000000..dc0a3b00 --- /dev/null +++ b/devdocs/vagrant/synced-folders%2Findex.html @@ -0,0 +1,6 @@ +<h1 id="synced-folders"> Synced Folders </h1> <p>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.</p> <p>By default, Vagrant will share your project directory (the directory with the <a href="../vagrantfile/index">Vagrantfile</a>) to <code>/vagrant</code>.</p> <p>Read the <a href="basic_usage">basic usage</a> page to get started with synced folders.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/synced-folders/" class="_attribution-link">https://www.vagrantup.com/docs/synced-folders/</a> + </p> +</div> diff --git a/devdocs/vagrant/synced-folders%2Fnfs.html b/devdocs/vagrant/synced-folders%2Fnfs.html new file mode 100644 index 00000000..1c564eb0 --- /dev/null +++ b/devdocs/vagrant/synced-folders%2Fnfs.html @@ -0,0 +1,57 @@ +<h1 id="nfs"> NFS </h1> <p>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, <a href="https://en.wikipedia.org/wiki/Network_File_System_%28protocol%29">NFS</a> can offer a solution. Vagrant has built-in support to orchestrate the configuration of the NFS server on the host and guest for you.</p> <blockquote class="alert alert-warning" role="alert"> <p><strong>Windows users:</strong> NFS folders do not work on Windows hosts. Vagrant will ignore your request for NFS synced folders on Windows.</p> </blockquote> <h2 id="prerequisites"> Prerequisites </h2> <p>Before using synced folders backed by NFS, the host machine must have <code>nfsd</code> installed, the NFS server daemon. This comes pre-installed on Mac OS X, and is typically a simple package install on Linux.</p> <p>Additionally, the guest machine must have NFS support installed. This is also usually a simple package installation away.</p> <p>If you are using the VirtualBox provider, you will also need to make sure you have a <a href="../networking/private_network">private network set up</a>. This is due to a limitation of VirtualBox's built-in networking. With VMware, you do not need this.</p> <h2 id="enabling-nfs-synced-folders"> Enabling NFS Synced Folders </h2> <p>To enable NFS, just add the <code>type: "nfs"</code> flag onto your synced folder:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.synced_folder ".", "/vagrant", type: "nfs" +end +</pre></div> +<p>If you add this to an existing Vagrantfile that has a running guest machine, be sure to <code>vagrant reload</code> to see your changes.</p> <h2 id="nfs-synced-folder-options"> NFS Synced Folder Options </h2> <p>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 <code>config.vm.synced_folder</code> definition, along with the <code>type</code> option.</p> <ul> <li> +<p><a href="#nfs_export"><code>nfs_export</code></a> (boolean) - If this is false, then Vagrant will not modify your <code>/etc/exports</code> automatically and assumes you've done so already.</p> </li> <li> +<p><a href="#nfs_udp"><code>nfs_udp</code></a> (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.</p> </li> <li> +<p><a href="#nfs_version"><code>nfs_version</code></a> (string | integer) - The NFS protocol version to use when mounting the folder on the guest. This defaults to 3.</p> </li> </ul> <h2 id="nfs-global-options"> NFS Global Options </h2> <p>There are also more global NFS options you can set with <code>config.nfs</code> in the Vagrantfile. These are documented below:</p> <ul> <li> +<p><a href="#functional"><code>functional</code></a> (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.</p> </li> <li> +<p><a href="#map_uid"><code>map_uid</code></a> and <code>map_gid</code> (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.</p> </li> <li> +<p><a href="#verify_installed"><code>verify_installed</code></a> (bool) - Defaults to true. If this is false, then Vagrant will skip checking if NFS is installed.</p> </li> </ul> <h2 id="specifying-nfs-arguments"> Specifying NFS Arguments </h2> <p>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 <code>mount_options</code> key. For example, to use the <code>actimeo=2</code> client mount option:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.synced_folder ".", "/vagrant", + type: "nfs", + mount_options: ['actimeo=2'] +</pre></div> +<p>This would result in the following <code>mount</code> command being executed on the guest:</p> <div class="highlight"><pre class="highlight plaintext">mount -o 'actimeo=2' 172.28.128.1:'/path/to/vagrantfile' /vagrant +</pre></div> +<p>You can also tweak the arguments specified in the <code>/etc/exports</code> template when the mount is added, by using the OS-specific <code>linux__nfs_options</code> or <code>bsd__nfs_options</code> keys. Note that these options completely override the default arguments that are added by Vagrant automatically. For example, to make the NFS share asynchronous:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.synced_folder ".", "/vagrant", + type: "nfs", + linux__nfs_options: ['rw','no_subtree_check','all_squash','async'] +</pre></div> +<p>This would result in the following content in <code>/etc/exports</code> on the host (note the added <code>async</code> flag):</p> <div class="highlight"><pre class="highlight plaintext"># 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 +</pre></div> +<h2 id="root-privilege-requirement"> Root Privilege Requirement </h2> <p>To configure NFS, Vagrant must modify system files on the host. Therefore, at some point during the <code>vagrant up</code> sequence, you may be prompted for administrative privileges (via the typical <code>sudo</code> program). These privileges are used to modify <code>/etc/exports</code> as well as to start and stop the NFS server daemon.</p> <p>If you do not want to type your password on every <code>vagrant up</code>, Vagrant uses thoughtfully crafted commands to make fine-grained sudoers modifications possible to avoid entering your password.</p> <p>Below, we have a couple example sudoers entries. Note that you may have to modify them <em>slightly</em> on certain hosts because the way Vagrant modifies <code>/etc/exports</code> changes a bit from OS to OS. If the commands below are located in non-standard paths, modify them as appropriate.</p> <p>For *nix users, make sure to edit your <code>/etc/sudoers</code> file with <code>visudo</code>. It protects you against syntax errors which could leave you without the ability to gain elevated privileges.</p> <p>All of the snippets below require Vagrant version 1.7.3 or higher.</p> <blockquote class="alert alert-warning" role="alert"> <p><strong>Use the appropriate group for your user</strong> Depending on how your machine is configured, you might need to use a different group than the ones listed in the examples below.</p> </blockquote> +<p>For OS X, sudoers should have this entry:</p> <div class="highlight"><pre class="highlight plaintext">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 +</pre></div> +<p>For Ubuntu Linux , sudoers should look like this:</p> <div class="highlight"><pre class="highlight plaintext">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 +</pre></div> +<p>For Fedora Linux, sudoers might look like this (given your user belongs to the vagrant group):</p> <div class="highlight"><pre class="highlight plaintext">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 +</pre></div> +<p>If you don't want to edit <code>/etc/sudoers</code> directly, you can create <code>/etc/sudoers.d/vagrant-syncedfolders</code> with the appropriate entries, assuming <code>/etc/sudoers.d</code> has been enabled.</p> <h2 id="other-notes"> Other Notes </h2> <p><strong>Encrypted folders:</strong> 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 <code><path> does not support NFS</code>. There is no workaround for this other than sharing a directory which is not encrypted.</p> <p><strong>Version 4:</strong> 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:</p> <div class="highlight"><pre class="highlight plaintext">mount.nfs: an incorrect mount option was specified +</pre></div> +<p>When using NFSv4, ensure the <code>nfs_udp</code> option is set to false. For example:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.synced_folder ".", "/vagrant", + type: "nfs", + nfs_version: 4, + nfs_udp: false +</pre></div> +<p>For more information about transport protocols and NFS version 4 see:</p> <ul> <li>NFSv4.0 - <a href="https://tools.ietf.org/html/rfc7530#section-3.1">RFC7530</a> </li> <li>NFSv4.1 - <a href="https://tools.ietf.org/html/rfc5661#section-2.9.1">RFC5661</a> </li> </ul><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/synced-folders/nfs.html" class="_attribution-link">https://www.vagrantup.com/docs/synced-folders/nfs.html</a> + </p> +</div> diff --git a/devdocs/vagrant/synced-folders%2Frsync.html b/devdocs/vagrant/synced-folders%2Frsync.html new file mode 100644 index 00000000..6e38d611 --- /dev/null +++ b/devdocs/vagrant/synced-folders%2Frsync.html @@ -0,0 +1,22 @@ +<h1 id="rsync"> RSync </h1> <p><strong>Synced folder type:</strong> <code>rsync</code></p> <p>Vagrant can use <a href="https://en.wikipedia.org/wiki/Rsync">rsync</a> 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.</p> <p>The rsync synced folder does a one-time one-way sync from the machine running to the machine being started by Vagrant.</p> <p>The <a href="../cli/rsync">rsync</a> and <a href="../cli/rsync-auto">rsync-auto</a> 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 <code>vagrant up</code> or <code>vagrant reload</code>.</p> <h2 id="prerequisites"> Prerequisites </h2> <p>To use the rsync synced folder type, the machine running Vagrant must have <code>rsync</code> (or <code>rsync.exe</code>) on the path. This executable is expected to behave like the standard rsync tool.</p> <p>On Windows, rsync installed with Cygwin or MinGW will be detected by Vagrant and works well.</p> <p>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.</p> <p>The destination folder will be created as the user initiating the connection, this is <code>vagrant</code> by default. This user requires the appropriate permissions on the destination folder.</p> <h2 id="options"> Options </h2> <p>The rsync synced folder type accepts the following options:</p> <ul> <li> +<p><a href="#rsync__args"><code>rsync__args</code></a> (array of strings) - A list of arguments to supply to <code>rsync</code>. By default this is <code>["--verbose", "--archive", "--delete", "-z", "--copy-links"]</code>.</p> </li> <li> +<p><a href="#rsync__auto"><code>rsync__auto</code></a> (boolean) - If false, then <code>rsync-auto</code> will not watch and automatically sync this folder. By default, this is true. <strong>Note</strong>: This option will not automatically invoke the <code>rsync-auto</code> subcommand.</p> </li> <li> +<p><a href="#rsync__chown"><code>rsync__chown</code></a> (boolean) - If false, then the <a href="basic_usage"><code>owner</code> and <code>group</code></a> options for the synced folder are ignored and Vagrant will not execute a recursive <code>chown</code>. This defaults to true. This option exists because the <code>chown</code> causes issues for some development environments. Note that any <code>rsync__args</code> options for ownership <strong>will be overridden</strong> by <code>rsync__chown</code>.</p> </li> <li> +<p><a href="#rsync__exclude"><code>rsync__exclude</code></a> (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.</p> </li> <li> +<p><a href="#rsync__rsync_path"><code>rsync__rsync_path</code></a> (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.</p> </li> <li> +<p><a href="#rsync__verbose"><code>rsync__verbose</code></a> (boolean) - If true, then the output from the rsync process will be echoed to the console. The output of rsync is subject to <code>rsync__args</code> of course. By default, this is false.</p> </li> </ul> <h2 id="example"> Example </h2> <p>The following is an example of using RSync to sync a folder:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.synced_folder ".", "/vagrant", type: "rsync", + rsync__exclude: ".git/" +end +</pre></div> +<h2 id="rsync-to-a-restricted-folder"> Rsync to a restricted folder </h2> <p>If required to copy to a destination where <code>vagrant</code> user does not have permissions, use <code>"--rsync-path='sudo rsync'"</code> to run rsync with sudo on the guest</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/synced-folders/rsync.html" class="_attribution-link">https://www.vagrantup.com/docs/synced-folders/rsync.html</a> + </p> +</div> diff --git a/devdocs/vagrant/synced-folders%2Fsmb.html b/devdocs/vagrant/synced-folders%2Fsmb.html new file mode 100644 index 00000000..ea6e6d16 --- /dev/null +++ b/devdocs/vagrant/synced-folders%2Fsmb.html @@ -0,0 +1,26 @@ +<h1 id="smb"> SMB </h1> <p><strong>Synced folder type:</strong> <code>smb</code></p> <p>Vagrant can use <a href="https://en.wikipedia.org/wiki/Server_Message_Block">SMB</a> as a mechanism to create a bi-directional synced folder between the host machine and the Vagrant machine.</p> <p>SMB is built-in to Windows machines and provides a higher performance alternative to some other mechanisms such as VirtualBox shared folders.</p> <blockquote class="alert alert-info"> <p>SMB is currently only supported when the host machine is Windows or macOS. The guest machine can be Windows, Linux, or macOS.</p> </blockquote> +<h2 id="prerequisites"> Prerequisites </h2> <h3 id="windows-host"> Windows Host </h3> <p>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.</p> <h3 id="macos-host"> macOS Host </h3> <p>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:</p> <ul> <li>Open "System Preferences" </li> <li>Click "Sharing" </li> <li>Check the "On" checkbox next to "File Sharing" </li> <li>Click "Options" </li> <li>Check "Share files and folders using SMB" </li> <li>Check the "On" checkbox next to your username within "Windows File Sharing" </li> <li>Click "Done" </li> </ul> <p>When Vagrant attempts to create new SMB shares, or remove existing SMB shares, root access will be required. Vagrant will request these privileges using <code>sudo</code> to run the <code>/usr/sbin/sharing</code> command. Adding the following to the system's <code>sudoers</code> configuration will allow Vagrant to manage SMB shares without requiring a password each time:</p> <div class="highlight"><pre class="highlight plaintext">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 +</pre></div> +<h3 id="guests"> Guests </h3> <p>The destination machine must be able to mount SMB filesystems. On Linux the package to do this is usually called <code>smbfs</code> or <code>cifs</code>. Vagrant knows how to automatically install this for some operating systems.</p> <h2 id="options"> Options </h2> <p>The SMB synced folder type has a variety of options it accepts:</p> <ul> <li> +<p><a href="#smb_host"><code>smb_host</code></a> (string) - The host IP where the SMB mount is located. If this is not specified, Vagrant will attempt to determine this automatically.</p> </li> <li> +<p><a href="#smb_password"><code>smb_password</code></a> (string) - The password used for authentication to mount the SMB mount. This is the password for the username specified by <code>smb_username</code>. 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.</p> </li> <li> +<p><a href="#smb_username"><code>smb_username</code></a> (string) - The username used for authentication to mount the SMB mount. This is the username to access the mount, <em>not</em> 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 <code>user@domain</code>. If this option is not specified, Vagrant will prompt you for it.</p> </li> </ul> <h2 id="example"> Example </h2> <p>The following is an example of using SMB to sync a folder:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.synced_folder ".", "/vagrant", type: "smb" +end +</pre></div> +<h2 id="preventing-idle-disconnects"> Preventing Idle Disconnects </h2> <p>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.</p> <div class="highlight"><pre class="highlight plaintext">net config server /autodisconnect:-1 +</pre></div> +<h2 id="common-issues"> Common Issues </h2> <h3 id="quot-wrong-fs-type-quot-error"> "wrong fs type" Error </h3> <p>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.</p> <p>If updating the kernel extension is not an option, you can workaround the issue by specifying the following options on your synced folder:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">mount_options: ["username=USERNAME","password=PASSWORD"] +</pre></div> +<p>Replace "USERNAME" and "PASSWORD" with your SMB username and password.</p> <p>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.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/synced-folders/smb.html" class="_attribution-link">https://www.vagrantup.com/docs/synced-folders/smb.html</a> + </p> +</div> diff --git a/devdocs/vagrant/synced-folders%2Fvirtualbox.html b/devdocs/vagrant/synced-folders%2Fvirtualbox.html new file mode 100644 index 00000000..37f4f1ff --- /dev/null +++ b/devdocs/vagrant/synced-folders%2Fvirtualbox.html @@ -0,0 +1,10 @@ +<h1 id="virtualbox"> VirtualBox </h1> <p>If you are using the Vagrant VirtualBox <a href="../providers/index">provider</a>, 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.</p> <h2 id="options"> Options </h2> <ul> <li> +<a href="#sharedfoldersenablesymlinkscreate"><code>SharedFoldersEnableSymlinksCreate</code></a> (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. </li> </ul> <h2 id="caveats"> Caveats </h2> <p>There is a <a href="https://github.com/hashicorp/vagrant/issues/351#issuecomment-1339640">VirtualBox bug</a> related to <code>sendfile</code> which can result in corrupted or non-updating files. You should deactivate <code>sendfile</code> in any web servers you may be running.</p> <p>In Nginx:</p> <div class="highlight"><pre class="highlight plaintext">sendfile off; +</pre></div> +<p>In Apache:</p> <div class="highlight"><pre class="highlight plaintext">EnableSendfile Off +</pre></div><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/synced-folders/virtualbox.html" class="_attribution-link">https://www.vagrantup.com/docs/synced-folders/virtualbox.html</a> + </p> +</div> diff --git a/devdocs/vagrant/triggers%2Fconfiguration.html b/devdocs/vagrant/triggers%2Fconfiguration.html new file mode 100644 index 00000000..2406f7ea --- /dev/null +++ b/devdocs/vagrant/triggers%2Fconfiguration.html @@ -0,0 +1,36 @@ +<h1 id="configuration"> Configuration </h1> <p>Vagrant Triggers has a few options to define trigger behavior.</p> <h2 id="options"> Options </h2> <p>The trigger class takes various options.</p> <ul> <li> +<p><a href="#action"><code>action</code></a> (symbol, array) - Expected to be a single symbol value, an array of symbols, or a <em>splat</em> of symbols. The first argument that comes after either <strong>before</strong> or <strong>after</strong> when defining a new trigger. Can be any valid Vagrant command. It also accepts a special value <code>:all</code> which will make the trigger fire for every action. An action can be ignored with the <code>ignore</code> setting if desired. These are the valid action commands for triggers:</p> <ul> <li> +<a href="#destroy"><code>destroy</code></a> </li> <li> +<a href="#halt"><code>halt</code></a> </li> <li> +<a href="#provision"><code>provision</code></a> </li> <li> +<a href="#reload"><code>reload</code></a> </li> <li> +<a href="#resume"><code>resume</code></a> </li> <li> +<a href="#suspend"><code>suspend</code></a> </li> <li> +<a href="#up"><code>up</code></a> </li> </ul> </li> <li> +<p><a href="#ignore"><code>ignore</code></a> (symbol, array) - Symbol or array of symbols corresponding to the action that a trigger should not fire on.</p> </li> <li> +<p><a href="#info"><code>info</code></a> (string) - A message that will be printed at the beginning of a trigger.</p> </li> <li> +<p><a href="#name"><code>name</code></a> (string) - The name of the trigger. If set, the name will be displayed when firing the trigger.</p> </li> <li> +<p><a href="#on_error"><code>on_error</code></a> (symbol) - Defines how the trigger should behave if it encounters an error. By default this will be <code>:halt</code>, but can be configured to ignore failures and continue on with <code>:continue</code>.</p> </li> <li> +<p><a href="#only_on"><code>only_on</code></a> (string, regex, array) - Limit the trigger to these guests. Values can be a string or regex that matches a guest name.</p> </li> <li> +<p><a href="#ruby"><code>ruby</code></a> (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: <code>env</code> and <code>machine</code>. 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 <code>Proc</code> type, which must be explicitly called out when using the hash syntax for a trigger.</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +</li> <li> +<p><a href="#run_remote"><code>run_remote</code></a> (hash) - A collection of settings to run a inline or remote script with on the guest. These settings correspond to the <a href="../provisioning/shell">shell provisioner</a>.</p> </li> <li> +<p><a href="#run"><code>run</code></a> (hash) - A collection of settings to run a inline or remote script on the host. These settings correspond to the <a href="../provisioning/shell">shell provisioner</a>. However, at the moment the only settings <code>run</code> takes advantage of are:</p> <ul> <li> +<a href="#args"><code>args</code></a> </li> <li> +<a href="#inline"><code>inline</code></a> </li> <li> +<a href="#path"><code>path</code></a> </li> </ul> </li> <li> +<p><a href="#warn"><code>warn</code></a> (string) - A warning message that will be printed at the beginning of a trigger.</p> </li> <li> +<p><a href="#exit_codes"><code>exit_codes</code></a> (integer, array) - A set of acceptable exit codes to continue on. Defaults to <code>0</code> if option is absent. For now only valid with the <code>run</code> option.</p> </li> <li> +<p><a href="#abort"><code>abort</code></a> (integer,boolean) - An option that will exit the running Vagrant process once the trigger fires. If set to <code>true</code>, Vagrant will use exit code 1. Otherwise, an integer can be provided and Vagrant will it as its exit code when aborting.</p> </li> </ul><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/triggers/configuration.html" class="_attribution-link">https://www.vagrantup.com/docs/triggers/configuration.html</a> + </p> +</div> diff --git a/devdocs/vagrant/triggers%2Findex.html b/devdocs/vagrant/triggers%2Findex.html new file mode 100644 index 00000000..9ec41dd2 --- /dev/null +++ b/devdocs/vagrant/triggers%2Findex.html @@ -0,0 +1,52 @@ +<h1 id="vagrant-triggers"> Vagrant Triggers </h1> <p>As of version 2.1.0, Vagrant is capable of executing machine triggers <em>before</em> or <em>after</em> Vagrant commands.</p> <p>Each trigger is expected to be given a command key for when it should be fired during the Vagrant command lifecycle. These could be defined as a single key or an array which acts like a <em>whitelist</em> for the defined trigger.</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby"># single command trigger +config.trigger.after :up do |trigger| +... +end + +# multiple commands for this trigger +config.trigger.before [:up, :destroy, :halt, :package] do |trigger| +... +end + +# or defined as a splat list +config.trigger.before :up, :destroy, :halt, :package do |trigger| +... +end +</pre></div> +<p>Alternatively, the key <code>:all</code> could be given which would run the trigger before or after every Vagrant command. If there is a command you don't want the trigger to run on, you can ignore that command with the <code>ignore</code> option.</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby"># single command trigger +config.trigger.before :all do |trigger| + trigger.info = "Running a before trigger!" + trigger.ignore = [:destroy, :halt] +end +</pre></div> +<p><strong>Note:</strong> <em>If a trigger is defined on a command that does not exist, a warning will be displayed.</em></p> <p>Triggers can be defined as a block or hash in a Vagrantfile. The example below will result in the same trigger:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.trigger.after :up do |trigger| + trigger.name = "Finished Message" + trigger.info = "Machine is up!" +end + +config.trigger.after :up, + name: "Finished Message", + info: "Machine is up!" +</pre></div> +<p>Triggers can also be defined within the scope of guests in a Vagrantfile. These triggers will only run on the configured guest. An example of a guest only trigger:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.define "ubuntu" do |ubuntu| + ubuntu.vm.box = "ubuntu" + ubuntu.trigger.before :destroy do |trigger| + trigger.warn = "Dumping database to /vagrant/outfile" + trigger.run_remote = {inline: "pg_dump dbname > /vagrant/outfile"} + end +end +</pre></div> +<p>Global and machine-scoped triggers will execute in the order that they are defined within a Vagrantfile. Take for example an abstracted Vagrantfile:</p> <div class="highlight"><pre class="highlight plaintext">Vagrantfile + global trigger 1 + global trigger 2 + machine defined + machine trigger 3 + global trigger 4 +end +</pre></div> +<p>In this generic case, the triggers would fire in the order: 1 -> 2 -> 3 -> 4</p> <p>For more information about what options are available for triggers, see the <a href="configuration">configuration section</a>.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/triggers/" class="_attribution-link">https://www.vagrantup.com/docs/triggers/</a> + </p> +</div> diff --git a/devdocs/vagrant/triggers%2Fusage.html b/devdocs/vagrant/triggers%2Fusage.html new file mode 100644 index 00000000..1a369d26 --- /dev/null +++ b/devdocs/vagrant/triggers%2Fusage.html @@ -0,0 +1,81 @@ +<h1 id="basic-usage"> Basic Usage </h1> <p>Below are some very simple examples of how to use Vagrant Triggers.</p> <h2 id="examples"> Examples </h2> <p>The following is a basic example of two global triggers. One that runs <em>before</em> the <code>:up</code> command and one that runs <em>after</em> the <code>:up</code> command:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.trigger.before :up do |trigger| + trigger.name = "Hello world" + trigger.info = "I am running before vagrant up!!" + end + + config.trigger.after :up do |trigger| + trigger.name = "Hello world" + trigger.info = "I am running after vagrant up!!" + end + + config.vm.define "ubuntu" do |ubuntu| + ubuntu.vm.box = "ubuntu" + end +end +</pre></div> +<p>These will run before and after each defined guest in the Vagrantfile.</p> <p>Running a remote script to save a database on your host before <strong>destroy</strong>ing a guest:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.define "ubuntu" do |ubuntu| + ubuntu.vm.box = "ubuntu" + + ubuntu.trigger.before :destroy do |trigger| + trigger.warn = "Dumping database to /vagrant/outfile" + trigger.run_remote = {inline: "pg_dump dbname > /vagrant/outfile"} + end + end +end +</pre></div> +<p>Now that the trigger is defined, running the <strong>destroy</strong> command will fire off the defined trigger before Vagrant destroys the machine.</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ vagrant destroy ubuntu +</pre></div> +<p>An example of defining three triggers that start and stop tinyproxy on your host machine using homebrew:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">#/bin/bash +# start-tinyproxy.sh +brew services start tinyproxy +</pre></div> +<div class="highlight"><pre class="highlight shell" data-language="shell">#/bin/bash +# stop-tinyproxy.sh +brew services stop tinyproxy +</pre></div> +<div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.define "ubuntu" do |ubuntu| + ubuntu.vm.box = "ubuntu" + + ubuntu.trigger.before :up do |trigger| + trigger.info = "Starting tinyproxy..." + trigger.run = {path: "start-tinyproxy.sh"} + end + + ubuntu.trigger.after :destroy, :halt do |trigger| + trigger.info = "Stopping tinyproxy..." + trigger.run = {path: "stop-tinyproxy.sh"} + end + end +end +</pre></div> +<p>Running <code>vagrant up</code> would fire the before trigger to start tinyproxy, where as running either <code>vagrant destroy</code> or <code>vagrant halt</code> would stop tinyproxy.</p> <h3 id="ruby-option"> Ruby Option </h3> <p>Triggers can also be defined to run Ruby, rather than bash or powershell. An example of this might be using a Ruby option to get more information from the <code>VBoxManage</code> tool. In this case, we are printing the <code>ostype</code> defined for thte guest after it has been brought up.</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.define "ubuntu" do |ubuntu| + ubuntu.vm.box = "ubuntu" + + ubuntu.trigger.after :up do |trigger| + trigger.info = "More information with ruby magic" + trigger.ruby do |env,machine| + puts `VBoxManage showvminfo #{machine.id} --machinereadable | grep ostype` + end + end + end +end +</pre></div> +<p>If you are defining your triggers using the hash syntax, you must use the <code>Proc</code> type for defining a ruby trigger.</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.define "ubuntu" do |ubuntu| + ubuntu.vm.box = "ubuntu" + + ubuntu.trigger.after :up, + info: "More information with ruby magic", + ruby: proc{|env,machine| puts `VBoxManage showvminfo #{machine.id} --machinereadable | grep ostype`} + end +end +</pre></div><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/triggers/usage.html" class="_attribution-link">https://www.vagrantup.com/docs/triggers/usage.html</a> + </p> +</div> diff --git a/devdocs/vagrant/vagrantfile%2Findex.html b/devdocs/vagrant/vagrantfile%2Findex.html new file mode 100644 index 00000000..732bb9ac --- /dev/null +++ b/devdocs/vagrant/vagrantfile%2Findex.html @@ -0,0 +1,14 @@ +<h1 id="vagrantfile"> Vagrantfile </h1> <p>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 <code>Vagrantfile</code> (casing does not matter unless your file system is running in a strict case sensitive mode).</p> <p>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 <code>vagrant up</code>, and be on their way. Vagrantfiles are portable across every platform Vagrant supports.</p> <p>The syntax of Vagrantfiles is <a href="http://www.ruby-lang.org">Ruby</a>, 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.</p> <h2 id="lookup-path"> Lookup Path </h2> <p>When you run any <code>vagrant</code> 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 <code>vagrant</code> in <code>/home/mitchellh/projects/foo</code>, it will search the following paths in order for a Vagrantfile, until it finds one:</p> <div class="highlight"><pre class="highlight plaintext">/home/mitchellh/projects/foo/Vagrantfile +/home/mitchellh/projects/Vagrantfile +/home/mitchellh/Vagrantfile +/home/Vagrantfile +/Vagrantfile +</pre></div> +<p>This feature lets you run <code>vagrant</code> from any directory in your project.</p> <p>You can change the starting directory where Vagrant looks for a Vagrantfile by setting the <code>VAGRANT_CWD</code> environmental variable to some other path.</p> <h2 id="load-order-and-merging"> Load Order and Merging </h2> <p>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.</p> <ol> <li>Vagrantfile packaged with the <a href="../boxes">box</a> that is to be used for a given machine. </li> <li>Vagrantfile in your Vagrant home directory (defaults to <code>~/.vagrant.d</code>). This lets you specify some defaults for your system user. </li> <li>Vagrantfile from the project directory. This is the Vagrantfile that you will be modifying most of the time. </li> <li> +<a href="../multi-machine/index">Multi-machine overrides</a> if any. </li> <li> +<a href="../providers/configuration">Provider-specific overrides</a>, if any. </li> </ol> <p>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.</p> <p>Within each Vagrantfile, you may specify multiple <code>Vagrant.configure</code> blocks. All configurations will be merged within a single Vagrantfile in the order they're defined.</p> <h2 id="available-configuration-options"> Available Configuration Options </h2> <p>You can learn more about the available configuration options by clicking the relevant section in the left navigational area.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/vagrantfile/" class="_attribution-link">https://www.vagrantup.com/docs/vagrantfile/</a> + </p> +</div> diff --git a/devdocs/vagrant/vagrantfile%2Fmachine_settings.html b/devdocs/vagrant/vagrantfile%2Fmachine_settings.html new file mode 100644 index 00000000..0a9082dc --- /dev/null +++ b/devdocs/vagrant/vagrantfile%2Fmachine_settings.html @@ -0,0 +1,31 @@ +<h1 id="machine-settings"> Machine Settings </h1> <p><strong>Config namespace: <code>config.vm</code></strong></p> <p>The settings within <code>config.vm</code> modify the configuration of the machine that Vagrant manages.</p> <h2 id="available-settings"> Available Settings </h2> <ul> <li> +<p><a href="#config-vm-base_mac" id="config-vm-base_mac"><code>config.vm.base_mac</code></a> (string) - The MAC address to be assigned to the default NAT interface on the guest. <em>Support for this option is provider dependent.</em></p> </li> <li> +<p><a href="#config-vm-base_address"><code>config.vm.base_address</code></a> (string) - The IP address to be assigned to the default NAT interface on the guest. <em>Support for this option is provider dependent.</em></p> </li> <li> +<p><a href="#config-vm-boot_timeout"><code>config.vm.boot_timeout</code></a> (integer) - The time in seconds that Vagrant will wait for the machine to boot and be accessible. By default this is 300 seconds.</p> </li> <li> +<p><a href="#config-vm-box"><code>config.vm.box</code></a> (string) - This configures what <a href="../boxes">box</a> 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 <a href="https://www.vagrantup.com/docs/vagrant-cloud">HashiCorp's Vagrant Cloud</a>.</p> </li> <li> +<p><a href="#config-vm-box_check_update"><code>config.vm.box_check_update</code></a> (boolean) - If true, Vagrant will check for updates to the configured box on every <code>vagrant up</code>. 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 <a href="https://www.vagrantup.com/docs/vagrant-cloud">HashiCorp's Vagrant Cloud</a> or some other versioned box).</p> </li> <li> +<p><a href="#config-vm-box_download_checksum"><code>config.vm.box_download_checksum</code></a> (string) - The checksum of the box specified by <code>config.vm.box_url</code>. 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 <code>config.vm.box_download_checksum_type</code> must also be specified.</p> </li> <li> +<p><a href="#config-vm-box_download_checksum_type"><code>config.vm.box_download_checksum_type</code></a> (string) - The type of checksum specified by <code>config.vm.box_download_checksum</code> (if any). Supported values are currently "md5", "sha1", and "sha256".</p> </li> <li> +<p><a href="#config-vm-box_download_client_cert"><code>config.vm.box_download_client_cert</code></a> (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.</p> </li> <li> +<p><a href="#config-vm-box_download_ca_cert"><code>config.vm.box_download_ca_cert</code></a> (string) - Path to a CA cert bundle to use when downloading a box directly. By default, Vagrant will use the Mozilla CA cert bundle.</p> </li> <li> +<p><a href="#config-vm-box_download_ca_path"><code>config.vm.box_download_ca_path</code></a> (string) - Path to a directory containing CA certificates for downloading a box directly. By default, Vagrant will use the Mozilla CA cert bundle.</p> </li> <li> +<p><a href="#config-vm-box_download_insecure"><code>config.vm.box_download_insecure</code></a> (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.</p> </li> <li> +<p><a href="#config-vm-box_download_location_trusted"><code>config.vm.box_download_location_trusted</code></a> (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.</p> </li> <li> +<p><a href="#config-vm-box_url"><code>config.vm.box_url</code></a> (string, array of strings) - The URL that the configured box can be found at. If <code>config.vm.box</code> is a shorthand to a box in <a href="https://www.vagrantup.com/docs/vagrant-cloud">HashiCorp's Vagrant Cloud</a> 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.</p> <p>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 <code>file://</code> scheme. For example: "file:///tmp/test.box".</p> </li> <li> +<p><a href="#config-vm-box_version"><code>config.vm.box_version</code></a> (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: <code>>= 1.0, < 1.5</code>. When constraints are given, Vagrant will use the latest available box satisfying these constraints.</p> </li> <li> +<p><a href="#config-vm-communicator"><code>config.vm.communicator</code></a> (string) - The communicator type to use to connect to the guest box. By default this is <code>"ssh"</code>, but should be changed to <code>"winrm"</code> for Windows guests.</p> </li> <li> +<p><a href="#config-vm-graceful_halt_timeout"><code>config.vm.graceful_halt_timeout</code></a> (integer) - The time in seconds that Vagrant will wait for the machine to gracefully halt when <code>vagrant halt</code> is called. Defaults to 60 seconds.</p> </li> <li> +<p><a href="#config-vm-guest"><code>config.vm.guest</code></a> (string, symbol) - The guest OS that will be running within this machine. This defaults to <code>:linux</code>, and Vagrant will auto-detect the proper distro. However, this should be changed to <code>:windows</code> for Windows guests. Vagrant needs to know this information to perform some guest OS-specific things such as mounting folders and configuring networks.</p> </li> <li> +<p><a href="#config-vm-hostname"><code>config.vm.hostname</code></a> (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 <code>/etc/hosts</code> on the guest with the configured hostname.</p> </li> <li> +<p><a href="#config-vm-ignore_box_vagrantfile"><code>config.vm.ignore_box_vagrantfile</code></a> (boolean) - If true, Vagrant will not load the the settings found inside a boxes Vagrantfile, if present. Defaults to <code>false</code>.</p> </li> <li> +<p><a href="#config-vm-network"><code>config.vm.network</code></a> - Configures <a href="../networking/index">networks</a> on the machine. Please see the networking page for more information.</p> </li> <li> +<p><a href="#config-vm-post_up_message"><code>config.vm.post_up_message</code></a> (string) - A message to show after <code>vagrant up</code>. This will be shown to the user and is useful for containing instructions such as how to access various components of the development environment.</p> </li> <li> +<p><a href="#config-vm-provider"><code>config.vm.provider</code></a> - Configures <a href="../providers/configuration">provider-specific configuration</a>, which is used to modify settings which are specific to a certain <a href="../providers/index">provider</a>. If the provider you are configuring does not exist or is not setup on the system of the person who runs <code>vagrant up</code>, 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.</p> </li> <li> +<p><a href="#config-vm-provision"><code>config.vm.provision</code></a> - Configures <a href="../provisioning/index">provisioners</a> 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.</p> </li> <li> +<p><a href="#config-vm-synced_folder"><code>config.vm.synced_folder</code></a> - Configures <a href="../synced-folders/index">synced folders</a> 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.</p> </li> <li> +<p><a href="#config-vm-usable_port_range"><code>config.vm.usable_port_range</code></a> (range) - A range of ports Vagrant can use for handling port collisions and such. Defaults to <code>2200..2250</code>.</p> </li> </ul><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/vagrantfile/machine_settings.html" class="_attribution-link">https://www.vagrantup.com/docs/vagrantfile/machine_settings.html</a> + </p> +</div> diff --git a/devdocs/vagrant/vagrantfile%2Fssh_settings.html b/devdocs/vagrant/vagrantfile%2Fssh_settings.html new file mode 100644 index 00000000..97042727 --- /dev/null +++ b/devdocs/vagrant/vagrantfile%2Fssh_settings.html @@ -0,0 +1,32 @@ +<h1 id="ssh-settings"> SSH Settings </h1> <p><strong>Config namespace: <code>config.ssh</code></strong></p> <p>The settings within <code>config.ssh</code> 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.</p> <h2 id="available-settings"> Available Settings </h2> <ul> <li> +<p><a href="#config-ssh-username" id="config-ssh-username"><code>config.ssh.username</code></a> (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.</p> </li> <li> +<p><a href="#config-ssh-password"><code>config.ssh.password</code></a> (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 <code>private_key_path</code>) below. If you use a password, Vagrant will automatically insert a keypair if <code>insert_key</code> is true.</p> </li> <li> +<p><a href="#config-ssh-host"><code>config.ssh.host</code></a> (string) - The hostname or IP to SSH into. By default this is empty, because the provider usually figures this out for you.</p> </li> <li> +<p><a href="#config-ssh-port"><code>config.ssh.port</code></a> (integer) - The port to SSH into. By default this is port 22.</p> </li> <li> +<p><a href="#config-ssh-guest_port"><code>config.ssh.guest_port</code></a> (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.</p> </li> <li> +<p><a href="#config-ssh-private_key_path"><code>config.ssh.private_key_path</code></a> (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.</p> </li> <li> +<p><a href="#config-ssh-keys_only"><code>config.ssh.keys_only</code></a> (boolean) - Only use Vagrant-provided SSH private keys (do not use any keys stored in ssh-agent). The default value is <code>true</code>.</p> </li> <li> +<p><a href="#config-ssh-verify_host_key"><code>config.ssh.verify_host_key</code></a> (string, symbol) - Perform strict host-key verification. The default value is <code>:never</code>.</p> </li> <li> +<p><a href="#config-ssh-paranoid"><code>config.ssh.paranoid</code></a> (boolean) - Perform strict host-key verification. The default value is <code>false</code>.</p> <p><strong>Deprecation:</strong> The <code>config.ssh.paranoid</code> option is deprecated and will be removed in a future release. Please use the <code>config.ssh.verify_host_key</code> option instead.</p> </li> <li> +<p><a href="#config-ssh-forward_agent"><code>config.ssh.forward_agent</code></a> (boolean) - If <code>true</code>, agent forwarding over SSH connections is enabled. Defaults to false.</p> </li> <li> +<p><a href="#config-ssh-forward_x11"><code>config.ssh.forward_x11</code></a> (boolean) - If <code>true</code>, X11 forwarding over SSH connections is enabled. Defaults to false.</p> </li> <li> +<p><a href="#config-ssh-forward_env"><code>config.ssh.forward_env</code></a> (array of strings) - An array of host environment variables to forward to the guest. If you are familiar with OpenSSH, this corresponds to the <code>SendEnv</code> parameter.</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.ssh.forward_env = ["CUSTOM_VAR"] +</pre></div> +</li> <li> +<p><a href="#config-ssh-insert_key"><code>config.ssh.insert_key</code></a> (boolean) - If <code>true</code>, Vagrant will automatically insert a keypair to use for SSH, replacing Vagrant's default insecure key inside the machine if detected. By default, this is true.</p> <p>This only has an effect if you do not already use private keys for authentication or if you are relying on the default insecure key. If you do not have to care about security in your project and want to keep using the default insecure key, set this to <code>false</code>.</p> </li> <li> +<p><a href="#config-ssh-proxy_command"><code>config.ssh.proxy_command</code></a> (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. <code>%h</code> in the command is replaced with the host and <code>%p</code> is replaced with the port.</p> </li> <li> +<p><a href="#config-ssh-pty"><code>config.ssh.pty</code></a> (boolean) - If <code>true</code>, pty will be used for provisioning. Defaults to false.</p> <p>This setting is an <em>advanced feature</em> 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.</p> <p>When pty is enabled, it is important to note that command output will <em>not</em> be streamed to the UI. Instead, the output will be delivered in full to the UI once the command has completed.</p> </li> <li> +<p><a href="#config-ssh-keep_alive"><code>config.ssh.keep_alive</code></a> (boolean) - If <code>true</code>, this setting SSH will send keep-alive packets every 5 seconds by default to keep connections alive.</p> </li> <li> +<p><a href="#config-ssh-shell"><code>config.ssh.shell</code></a> (string) - The shell to use when executing SSH commands from Vagrant. By default this is <code>bash -l</code>. Note that this has no effect on the shell you get when you run <code>vagrant ssh</code>. This configuration option only affects the shell to use when executing commands internally in Vagrant.</p> </li> <li> +<p><a href="#config-ssh-export_command_template"><code>config.ssh.export_command_template</code></a> (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: <code>%ENV_KEY%</code> and <code>%ENV_VALUE%</code>. The default template is:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.ssh.export_command_template = 'export %ENV_KEY%="%ENV_VALUE%"' +</pre></div> +</li> <li> +<p><a href="#config-ssh-sudo_command"><code>config.ssh.sudo_command</code></a> (string) - The command to use when executing a command with <code>sudo</code>. This defaults to <code>sudo -E -H %c</code>. The <code>%c</code> will be replaced by the command that is being executed.</p> </li> <li> +<p><a href="#config-ssh-compression"><code>config.ssh.compression</code></a> (boolean) - If <code>false</code>, this setting will not include the compression setting when ssh'ing into a machine. If this is not set, it will default to <code>true</code> and <code>Compression=yes</code> will be enabled with ssh.</p> </li> <li> +<p><a href="#config-ssh-dsa_authentication"><code>config.ssh.dsa_authentication</code></a> (boolean) - If <code>false</code>, this setting will not include <code>DSAAuthentication</code> when ssh'ing into a machine. If this is not set, it will default to <code>true</code> and <code>DSAAuthentication=yes</code> will be used with ssh.</p> </li> <li> +<p><a href="#config-ssh-extra_args"><code>config.ssh.extra_args</code></a> (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 <code>"-6"</code> for IPV6 or an array of arguments such as <code>["-L", "8008:localhost:80"]</code> for enabling a tunnel from host port 8008 to port 80 on guest.</p> </li> </ul><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/vagrantfile/ssh_settings.html" class="_attribution-link">https://www.vagrantup.com/docs/vagrantfile/ssh_settings.html</a> + </p> +</div> diff --git a/devdocs/vagrant/vagrantfile%2Ftips.html b/devdocs/vagrant/vagrantfile%2Ftips.html new file mode 100644 index 00000000..c16e3e16 --- /dev/null +++ b/devdocs/vagrant/vagrantfile%2Ftips.html @@ -0,0 +1,27 @@ +<h1 id="tips-amp-tricks"> Tips & Tricks </h1> <p>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.</p> <h2 id="loop-over-vm-definitions"> Loop Over VM Definitions </h2> <p>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:</p> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<blockquote class="alert alert-warning" role="alert"> <p><strong>Warning:</strong> 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 <em>does not work</em>:</p> </blockquote> <div class="highlight"><pre class="highlight ruby" data-language="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 +</pre></div> +<p>The <code>for i in ...</code> construct in Ruby actually modifies the value of <code>i</code> for each iteration, rather than making a copy. Therefore, when you run this, every node will actually provision with the same text.</p> <p>This is an easy mistake to make, and Vagrant cannot really protect against it, so the best we can do is mention it here.</p> <h2 id="overwrite-host-locale-in-ssh-session"> Overwrite host locale in ssh session </h2> <p>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 <code>Vagrantfile</code>:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">ENV["LC_ALL"] = "en_US.UTF-8" + +Vagrant.configure("2") do |config| + # ... +end +</pre></div> +<p>The change is only visible within the <code>Vagrantfile</code>.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/vagrantfile/tips.html" class="_attribution-link">https://www.vagrantup.com/docs/vagrantfile/tips.html</a> + </p> +</div> diff --git a/devdocs/vagrant/vagrantfile%2Fvagrant_settings.html b/devdocs/vagrant/vagrantfile%2Fvagrant_settings.html new file mode 100644 index 00000000..9c467317 --- /dev/null +++ b/devdocs/vagrant/vagrantfile%2Fvagrant_settings.html @@ -0,0 +1,20 @@ +<h1 id="vagrant-settings"> Vagrant Settings </h1> <p><strong>Config namespace: <code>config.vagrant</code></strong></p> <p>The settings within <code>config.vagrant</code> modify the behavior of Vagrant itself.</p> <h2 id="available-settings"> Available Settings </h2> <ul> <li> +<p><a href="#config-vagrant-host" id="config-vagrant-host"><code>config.vagrant.host</code></a> (string, symbol) - This sets the type of host machine that is running Vagrant. By default this is <code>:detect</code>, 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.</p> </li> <li> +<p><a href="#config-vagrant-plugins"><code>config.vagrant.plugins</code></a> - (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:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vagrant.plugins = "vagrant-plugin" +</pre></div> +<p>If multiple plugins are required, they can be provided as an array:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vagrant.plugins = ["vagrant-plugin", "vagrant-other-plugin"] +</pre></div> +<p>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:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vagrant.plugins = {"vagrant-scp" => {"version" => "1.0.0"}} +</pre></div> +<p>Supported options are:</p> <ul> <li> +<a href="#entry_point"><code>entry_point</code></a> - Path for Vagrant to load plugin </li> <li> +<a href="#sources"><code>sources</code></a> - Custom sources for downloading plugin </li> <li> +<a href="#version"><code>version</code></a> - Version constraint for plugin </li> </ul> </li> <li> +<p><a href="#config-vagrant-sensitive"><code>config.vagrant.sensitive</code></a> - (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.</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vagrant.sensitive = ["MySecretPassword", ENV["MY_TOKEN"]] +</pre></div> +</li> </ul><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/vagrantfile/vagrant_settings.html" class="_attribution-link">https://www.vagrantup.com/docs/vagrantfile/vagrant_settings.html</a> + </p> +</div> diff --git a/devdocs/vagrant/vagrantfile%2Fvagrant_version.html b/devdocs/vagrant/vagrantfile%2Fvagrant_version.html new file mode 100644 index 00000000..762454fc --- /dev/null +++ b/devdocs/vagrant/vagrantfile%2Fvagrant_version.html @@ -0,0 +1,9 @@ +<h1 id="minimum-vagrant-version"> Minimum Vagrant Version </h1> <p>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.</p> <p>Vagrant version requirements should be specified at the top of a Vagrantfile with the <code>Vagrant.require_version</code> helper:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.require_version ">= 1.3.5" +</pre></div> +<p>In the case above, the Vagrantfile will only load if the version loading it is Vagrant 1.3.5 or greater.</p> <p>Multiple requirements can be specified as well:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.require_version ">= 1.3.5", "< 1.4.0" +</pre></div><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/vagrantfile/vagrant_version.html" class="_attribution-link">https://www.vagrantup.com/docs/vagrantfile/vagrant_version.html</a> + </p> +</div> diff --git a/devdocs/vagrant/vagrantfile%2Fversion.html b/devdocs/vagrant/vagrantfile%2Fversion.html new file mode 100644 index 00000000..81ea1ecc --- /dev/null +++ b/devdocs/vagrant/vagrantfile%2Fversion.html @@ -0,0 +1,18 @@ +<h1 id="configuration-version"> Configuration Version </h1> <p>Configuration versions are the mechanism by which Vagrant 1.1+ is able to remain <a href="../installation/backwards-compatibility">backwards compatible</a> with Vagrant 1.0.x Vagrantfiles, while introducing dramatically new features and configuration options.</p> <p>If you run <code>vagrant init</code> today, the Vagrantfile will be in roughly the following format:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + # ... +end +</pre></div> +<p>The <code>"2"</code> in the first line above represents the version of the configuration object <code>config</code> that will be used for configuration for that block (the section between the <code>do</code> and the <code>end</code>). This object can be very different from version to version.</p> <p>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.</p> <p>When loading Vagrantfiles, Vagrant uses the proper configuration object for each version, and properly merges them, just like any other configuration.</p> <p>The important thing to understand as a general user of Vagrant is that <em>within a single configuration section</em>, only a single version can be used. You cannot use the new <code>config.vm.provider</code> configurations in a version 1 configuration section. Likewise, <code>config.vm.forward_port</code> will not work in a version 2 configuration section (it was renamed).</p> <p>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:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("1") do |config| + # v1 configs... +end + +Vagrant.configure("2") do |config| + # v2 configs... +end +</pre></div> +<blockquote class="alert alert-info"> <p><strong>What is <code>Vagrant::Config.run</code>?</strong> You may see this in Vagrantfiles. This was actually how Vagrant 1.0.x did configuration. In Vagrant 1.1+, this is synonymous with <code>Vagrant.configure("1")</code>.</p> </blockquote><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/vagrantfile/version.html" class="_attribution-link">https://www.vagrantup.com/docs/vagrantfile/version.html</a> + </p> +</div> diff --git a/devdocs/vagrant/vagrantfile%2Fwinrm_settings.html b/devdocs/vagrant/vagrantfile%2Fwinrm_settings.html new file mode 100644 index 00000000..066a2352 --- /dev/null +++ b/devdocs/vagrant/vagrantfile%2Fwinrm_settings.html @@ -0,0 +1,18 @@ +<h1 id="winrm-settings"> WinRM Settings </h1> <p><strong>Config namespace: <code>config.winrm</code></strong></p> <p>The settings within <code>config.winrm</code> 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.</p> <p>These settings are only used if you've set your communicator type to <code>:winrm</code>.</p> <h2 id="available-settings"> Available Settings </h2> <ul> <li> +<p><a href="#config-winrm-username" id="config-winrm-username"><code>config.winrm.username</code></a> (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.</p> </li> <li> +<p><a href="#config-winrm-password"><code>config.winrm.password</code></a> (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.</p> </li> <li> +<p><a href="#config-winrm-host"><code>config.winrm.host</code></a> (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.</p> </li> <li> +<p><a href="#config-winrm-port"><code>config.winrm.port</code></a> (integer) - The WinRM port to connect to, by default 5985.</p> </li> <li> +<p><a href="#config-winrm-guest_port"><code>config.winrm.guest_port</code></a> (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.</p> </li> <li> +<p><a href="#config-winrm-transport"><code>config.winrm.transport</code></a> (symbol)- The transport used for WinRM communication. Valid settings include: <code>:negotiate</code>, <code>:ssl</code>, and <code>:plaintext</code>. The default is <code>:negotiate</code>.</p> </li> <li> +<p><a href="#config-winrm-basic_auth_only"><code>config.winrm.basic_auth_only</code></a> (boolean) - Whether to use Basic Authentication. Defaults to <code>false</code>. If set to <code>true</code> you should also use the <code>:plaintext</code> transport setting and the Windows machine must be configured appropriately.</p> <p><strong>Note:</strong> It is strongly recommended that you only use basic authentication for debugging purposes. Credentials will be transferred in plain text.</p> </li> <li> +<p><a href="#config-winrm-ssl_peer_verification"><code>config.winrm.ssl_peer_verification</code></a> (boolean) - When set to <code>false</code> ssl certificate validation is not performed.</p> </li> <li> +<p><a href="#config-winrm-timeout"><code>config.winrm.timeout</code></a> (integer) - The maximum amount of time to wait for a response from the endpoint. This defaults to 60 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.</p> </li> <li> +<p><a href="#config-winrm-retry_limit"><code>config.winrm.retry_limit</code></a> (integer) - The maximum number of times to retry opening a shell after failure. This defaults to 3.</p> </li> <li> +<p><a href="#config-winrm-retry_delay"><code>config.winrm.retry_delay</code></a> (integer) - The amount of time to wait between retries and defaults to 10 seconds.</p> </li> <li> +<p><a href="#config-winrm-codepage"><code>config.winrm.codepage</code></a> (string) - The WINRS_CODEPAGE which is the client's console output code page. The default is 65001 (UTF-8).</p> <p><strong>Note:</strong> 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 <code>chcp</code> command can be used to determine the value of the native codepage.</p> </li> </ul><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/vagrantfile/winrm_settings.html" class="_attribution-link">https://www.vagrantup.com/docs/vagrantfile/winrm_settings.html</a> + </p> +</div> diff --git a/devdocs/vagrant/vagrantfile%2Fwinssh_settings.html b/devdocs/vagrant/vagrantfile%2Fwinssh_settings.html new file mode 100644 index 00000000..76ace77b --- /dev/null +++ b/devdocs/vagrant/vagrantfile%2Fwinssh_settings.html @@ -0,0 +1,20 @@ +<h1 id="winssh"> WinSSH </h1> <p>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.</p> <p>For more information, see the <a href="https://github.com/PowerShell/Win32-OpenSSH/">Win32-OpenSSH project page</a>.</p> <h1 id="winssh-settings"> WinSSH Settings </h1> <p>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.</p> <p>The configuration options below are specific to the WinSSH communicator.</p> <p><strong>Config namespace: <code>config.winssh</code></strong></p> <h2 id="available-settings"> Available Settings </h2> <ul> <li> +<p><a href="#config-winssh-forward_agent"><code>config.winssh.forward_agent</code></a> (boolean) - If <code>true</code>, agent forwarding over SSH connections is enabled. Defaults to false.</p> </li> <li> +<p><a href="#config-winssh-forward_env"><code>config.winssh.forward_env</code></a> (array of strings) - An array of host environment variables to forward to the guest. If you are familiar with OpenSSH, this corresponds to the <code>SendEnv</code> parameter.</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.winssh.forward_env = ["CUSTOM_VAR"] +</pre></div> +</li> <li> +<p><a href="#config-winssh-proxy_command"><code>config.winssh.proxy_command</code></a> (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. <code>%h</code> in the command is replaced with the host and <code>%p</code> is replaced with the port.</p> </li> <li> +<p><a href="#config-winssh-keep_alive"><code>config.winssh.keep_alive</code></a> (boolean) - If <code>true</code>, this setting SSH will send keep-alive packets every 5 seconds by default to keep connections alive.</p> </li> <li> +<p><a href="#config-winssh-shell"><code>config.winssh.shell</code></a> (string) - The shell to use when executing SSH commands from Vagrant. By default this is <code>cmd</code>. Valid values are <code>"cmd"</code> or <code>"powershell"</code>. Note that this has no effect on the shell you get when you run <code>vagrant ssh</code>. This configuration option only affects the shell to use when executing commands internally in Vagrant.</p> </li> <li> +<p><a href="#config-winssh-export_command_template"><code>config.winssh.export_command_template</code></a> (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: <code>%ENV_KEY%</code> and <code>%ENV_VALUE%</code>. The default template for a <code>cmd</code> configured shell is:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.winssh.export_command_template = 'set %ENV_KEY%="%ENV_VALUE%"' +</pre></div> +<p>The default template for a <code>powershell</code> configured shell is:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.winssh.export_command_template = '$env:%ENV_KEY%="%ENV_VALUE%"' +</pre></div> +</li> <li> +<p><a href="#config-winssh-sudo_command"><code>config.winssh.sudo_command</code></a> (string) - The command to use when executing a command with <code>sudo</code>. This defaults to <code>%c</code> (assumes vagrant user is an administrator and needs no escalation). The <code>%c</code> will be replaced by the command that is being executed.</p> </li> <li> +<p><a href="#config-winssh-upload_directory"><code>config.winssh.upload_directory</code></a> (string) - The upload directory used on the guest to store scripts for execute. This is set to <code>C:\Windows\Temp</code> by default.</p> </li> </ul><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/vagrantfile/winssh_settings.html" class="_attribution-link">https://www.vagrantup.com/docs/vagrantfile/winssh_settings.html</a> + </p> +</div> diff --git a/devdocs/vagrant/virtualbox%2Fboxes.html b/devdocs/vagrant/virtualbox%2Fboxes.html new file mode 100644 index 00000000..bb4e4bad --- /dev/null +++ b/devdocs/vagrant/virtualbox%2Fboxes.html @@ -0,0 +1,34 @@ +<h1 id="creating-a-base-box"> Creating a Base Box </h1> <p>As with <a href="../providers/basic_usage">every Vagrant provider</a>, the Vagrant VirtualBox provider has a custom box format that affects how base boxes are made.</p> <p>Prior to reading this, you should read the <a href="../boxes/base">general guide to creating base boxes</a>. 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.</p> <p>Additionally, it is helpful to understand the <a href="../boxes/format">basics of the box file format</a>.</p> <blockquote class="alert alert-warning"> <p><strong>Advanced topic!</strong> 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.</p> </blockquote> +<h2 id="virtual-machine"> Virtual Machine </h2> <p>The virtual machine created in VirtualBox can use any configuration you would like, but Vagrant has some hard requirements:</p> <ul> <li> +<p>The first network interface (adapter 1) <em>must</em> be a NAT adapter. Vagrant uses this to connect the first time.</p> </li> <li> +<p>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 <code>config.vm.base_mac</code>. To get this value, use the VirtualBox GUI.</p> </li> </ul> <p>Other than the above, you are free to customize the base virtual machine as you see fit.</p> <h2 id="additional-software"> Additional Software </h2> <p>In addition to the software that should be installed based on the <a href="../boxes/base">general guide to creating base boxes</a>, VirtualBox base boxes require some additional software.</p> <h3 id="virtualbox-guest-additions"> VirtualBox Guest Additions </h3> <p><a href="https://www.virtualbox.org/manual/ch04.html">VirtualBox Guest Additions</a> 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.</p> <p>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:</p> <div class="highlight"><pre class="highlight plaintext">$ sudo apt-get install linux-headers-$(uname -r) build-essential dkms +</pre></div> +<h4 id="to-install-via-the-gui-"> To install via the GUI: </h4> <p>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:</p> <div class="highlight"><pre class="highlight plaintext">$ sudo mount /dev/cdrom /media/cdrom +</pre></div> +<p>Finally, run the shell script that matches your system to install the guest additions. For example, for Linux on x86, it is the following:</p> <div class="highlight"><pre class="highlight plaintext">$ sudo sh /media/cdrom/VBoxLinuxAdditions.run +</pre></div> +<p>If the command succeeds, then the guest additions are now installed!</p> <h4 id="to-install-via-the-command-line-"> To install via the command line: </h4> <p>You can find the appropriate guest additions version to match your VirtualBox version by selecting the appropriate version <a href="http://download.virtualbox.org/virtualbox/">here</a>. The examples below use 4.3.8, which was the latest VirtualBox version at the time of writing.</p> <div class="highlight"><pre class="highlight plaintext">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 +</pre></div> +<p>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.</p> <p>If the commands succeed, then the guest additions are now installed!</p> <h2 id="packaging-the-box"> Packaging the Box </h2> <p>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:</p> <div class="highlight"><pre class="highlight plaintext">$ vagrant package --base my-virtual-machine +</pre></div> +<p>Where "my-virtual-machine" is replaced by the name of the virtual machine in VirtualBox to package as a base box.</p> <p>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!</p> <h2 id="raw-contents"> Raw Contents </h2> <p>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.</p> <p>A VirtualBox base box is an archive of the resulting files of <a href="https://www.virtualbox.org/manual/ch08.html#vboxmanage-export">exporting</a> a VirtualBox virtual machine. Here is an example of what is contained in such a box:</p> <div class="highlight"><pre class="highlight plaintext">$ tree +. +|-- Vagrantfile +|-- box-disk1.vmdk +|-- box.ovf +|-- metadata.json + +0 directories, 4 files +</pre></div> +<p>In addition to the files from exporting a VirtualBox VM, there is the "metadata.json" file used by Vagrant itself.</p> <p>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 <code>vagrant package --base</code> above, you will have to set the <code>config.vm.base_mac</code> setting in this Vagrantfile to the MAC address of the NAT device without colons.</p> <p>When bringing up a VirtualBox backed machine, Vagrant <a href="https://www.virtualbox.org/manual/ch08.html#vboxmanage-import">imports</a> the "box.ovf" file found in the box contents.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/virtualbox/boxes.html" class="_attribution-link">https://www.vagrantup.com/docs/virtualbox/boxes.html</a> + </p> +</div> diff --git a/devdocs/vagrant/virtualbox%2Fcommon-issues.html b/devdocs/vagrant/virtualbox%2Fcommon-issues.html new file mode 100644 index 00000000..83185b6b --- /dev/null +++ b/devdocs/vagrant/virtualbox%2Fcommon-issues.html @@ -0,0 +1,6 @@ +<h1 id="common-issues"> Common Issues </h1> <p>This page lists some common issues people run into with Vagrant and VirtualBox as well as solutions for those issues.</p> <h2 id="hanging-on-windows"> Hanging on Windows </h2> <p>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.</p> <p>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.</p> <h2 id="dns-not-working"> DNS Not Working </h2> <p>If DNS is not working within your VM, then you may need to enable a DNS proxy (built-in to VirtualBox). Please <a href="https://serverfault.com/questions/453185/vagrant-virtualbox-dns-10-0-2-3-not-working">see the StackOverflow answers here</a> for a guide on how to do that.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/virtualbox/common-issues.html" class="_attribution-link">https://www.vagrantup.com/docs/virtualbox/common-issues.html</a> + </p> +</div> diff --git a/devdocs/vagrant/virtualbox%2Fconfiguration.html b/devdocs/vagrant/virtualbox%2Fconfiguration.html new file mode 100644 index 00000000..4f2b5631 --- /dev/null +++ b/devdocs/vagrant/virtualbox%2Fconfiguration.html @@ -0,0 +1,33 @@ +<h1 id="configuration"> Configuration </h1> <p>The VirtualBox provider exposes some additional configuration options that allow you to more finely control your VirtualBox-powered Vagrant environments.</p> <h2 id="gui-vs-headless"> GUI vs. Headless </h2> <p>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:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.provider "virtualbox" do |v| + v.gui = true +end +</pre></div> +<h2 id="virtual-machine-name"> Virtual Machine Name </h2> <p>You can customize the name that appears in the VirtualBox GUI by setting the <code>name</code> 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.</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.provider "virtualbox" do |v| + v.name = "my_vm" +end +</pre></div> +<h2 id="linked-clones"> Linked Clones </h2> <p>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.</p> <p>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.</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.provider "virtualbox" do |v| + v.linked_clone = true +end +</pre></div> +<p>To have backward compatibility:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.provider 'virtualbox' do |v| + v.linked_clone = true if Gem::Version.new(Vagrant::VERSION) >= Gem::Version.new('1.8.0') +end +</pre></div> +<p>If you do not want backward compatibility and want to force users to support linked cloning, you can use <code>Vagrant.require_version</code> with 1.8.</p> <blockquote class="alert alert-info"> <p><strong>Note:</strong> 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.</p> </blockquote> +<h2 id="vboxmanage-customizations"> VBoxManage Customizations </h2> <p><a href="https://www.virtualbox.org/manual/ch08.html">VBoxManage</a> is a utility that can be used to make modifications to VirtualBox virtual machines from the command line.</p> <p>Vagrant exposes a way to call any command against VBoxManage just prior to booting the machine:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.provider "virtualbox" do |v| + v.customize ["modifyvm", :id, "--cpuexecutioncap", "50"] +end +</pre></div> +<p>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:</p> <ul> <li> +<p>The <code>:id</code> 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.</p> </li> <li> +<p>Multiple <code>customize</code> directives can be used. They will be executed in the order given.</p> </li> </ul> <p>There are some convenience shortcuts for memory and CPU settings:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.provider "virtualbox" do |v| + v.memory = 1024 + v.cpus = 2 +end +</pre></div><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/virtualbox/configuration.html" class="_attribution-link">https://www.vagrantup.com/docs/virtualbox/configuration.html</a> + </p> +</div> diff --git a/devdocs/vagrant/virtualbox%2Findex.html b/devdocs/vagrant/virtualbox%2Findex.html new file mode 100644 index 00000000..8e4969b0 --- /dev/null +++ b/devdocs/vagrant/virtualbox%2Findex.html @@ -0,0 +1,6 @@ +<h1 id="virtualbox"> VirtualBox </h1> <p>Vagrant comes with support out of the box for <a href="https://www.virtualbox.org">VirtualBox</a>, a free, cross-platform consumer virtualization product.</p> <p>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, and 5.2.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.</p> <p>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 <a href="https://www.virtualbox.org/wiki/Downloads">downloading</a> a package or installer for your operating system and using standard procedures to install that package.</p> <p>Use the navigation to the left to find a specific VirtualBox topic to read more about.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/virtualbox/" class="_attribution-link">https://www.vagrantup.com/docs/virtualbox/</a> + </p> +</div> diff --git a/devdocs/vagrant/virtualbox%2Fnetworking.html b/devdocs/vagrant/virtualbox%2Fnetworking.html new file mode 100644 index 00000000..0290178f --- /dev/null +++ b/devdocs/vagrant/virtualbox%2Fnetworking.html @@ -0,0 +1,20 @@ +<h1 id="networking"> Networking </h1> <h2 id="virtualbox-internal-network"> VirtualBox Internal Network </h2> <p>The Vagrant VirtualBox provider supports using the private network as a VirtualBox <a href="https://www.virtualbox.org/manual/ch06.html#network_internal">internal network</a>. By default, private networks are host-only networks, because those are the easiest to work with. However, internal networks can be enabled as well.</p> <p>To specify a private network as an internal network for VirtualBox use the <code>virtualbox__intnet</code> option with the network. The <code>virtualbox__</code> (double underscore) prefix tells Vagrant that this option is only for the VirtualBox provider.</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.network "private_network", ip: "192.168.50.4", + virtualbox__intnet: true +end +</pre></div> +<p>Additionally, if you want to specify that the VirtualBox provider join a specific internal network, specify the name of the internal network:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.network "private_network", ip: "192.168.50.4", + virtualbox__intnet: "mynetwork" +end +</pre></div> +<h2 id="virtualbox-nic-type"> VirtualBox NIC Type </h2> <p>You can specify a specific NIC type for the created network interface by using the <code>nic_type</code> parameter. This is not prefixed by <code>virtualbox__</code> for legacy reasons, but is VirtualBox-specific.</p> <p>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.</p> <p>Example:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.network "private_network", ip: "192.168.50.4", + nic_type: "virtio" +end +</pre></div><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/virtualbox/networking.html" class="_attribution-link">https://www.vagrantup.com/docs/virtualbox/networking.html</a> + </p> +</div> diff --git a/devdocs/vagrant/virtualbox%2Fusage.html b/devdocs/vagrant/virtualbox%2Fusage.html new file mode 100644 index 00000000..3a6e2959 --- /dev/null +++ b/devdocs/vagrant/virtualbox%2Fusage.html @@ -0,0 +1,6 @@ +<h1 id="usage"> Usage </h1> <p>The Vagrant VirtualBox provider is used just like any other provider. Please read the general <a href="../providers/basic_usage">basic usage</a> page for providers.</p> <p>The value to use for the <code>--provider</code> flag is <code>virtualbox</code>.</p> <p>The Vagrant VirtualBox provider does not support parallel execution at this time. Specifying the <code>--parallel</code> option will have no effect.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/virtualbox/usage.html" class="_attribution-link">https://www.vagrantup.com/docs/virtualbox/usage.html</a> + </p> +</div> diff --git a/devdocs/vagrant/vmware%2Fboxes.html b/devdocs/vagrant/vmware%2Fboxes.html new file mode 100644 index 00000000..09791970 --- /dev/null +++ b/devdocs/vagrant/vmware%2Fboxes.html @@ -0,0 +1,40 @@ +<h1 id="boxes"> Boxes </h1> <p>As with <a href="../providers/basic_usage">every Vagrant provider</a>, the Vagrant VMware providers have a custom box format.</p> <p>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.</p> <blockquote class="alert alert-info"> <p><strong>Note:</strong> 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.</p> </blockquote> +<p>Prior to reading this page, please understand the <a href="../boxes/format">basics of the box file format</a>.</p> <h2 id="contents"> Contents </h2> <p>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:</p> <div class="highlight"><pre class="highlight plaintext">$ tree +. +|-- disk-s001.vmdk +|-- disk-s002.vmdk +|-- ... +|-- disk.vmdk +|-- metadata.json +|-- precise64.nvram +|-- precise64.vmsd +|-- precise64.vmx +|-- precise64.vmxf + +0 directories, 17 files +</pre></div> +<p>The files that are strictly required for a VMware machine to function are: nvram, vmsd, vmx, vmxf, and vmdk files.</p> <p>There is also the "metadata.json" file used by Vagrant itself. This file contains nothing but the defaults which are documented on the <a href="../boxes/format">box format</a> page.</p> <p>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.</p> <blockquote class="alert alert-info"> <p><strong>Vagrant 1.8 and higher support linked clones</strong>. Prior versions of Vagrant do not support linked clones. For more information on linked clones, please see the documentation.</p> </blockquote> +<h2 id="vmx-whitelisting"> VMX Whitelisting </h2> <p>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 <a href="https://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames/">"predictable network interface names"</a> 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.</p> <p>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.</p> <h3 id="making-compatible-boxes"> Making compatible boxes </h3> <p>These are the VMX settings the whitelisting applies to:</p> <ul> <li> +<a href="#ethernet-pcislotnumber"><code>ethernet*.pcislotnumber</code></a> </li> </ul> <p>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:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + ["vmware_workstation", "vmware_fusion"].each do |vmware_provider| + config.vm.provider(vmware_provider) do |vmware| + vmware.whitelist_verified = true + end + end +end +</pre></div> +<p>This will prevent Vagrant from displaying a warning to the user as well as disable the VMX settings modifications.</p> <h2 id="installed-software"> Installed Software </h2> <p>Base boxes for VMware should have the following software installed, as a bare minimum:</p> <ul> <li> +<p>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 <a href="https://github.com/hashicorp/vagrant/blob/master/keys/vagrant.pub">insecure keypair</a> that ships with Vagrant.</p> </li> <li> +<p><a href="https://kb.vmware.com/kb/340">VMware Tools</a> so that things such as shared folders can function. There are many other benefits to installing the tools, such as improved networking performance.</p> </li> </ul> <h2 id="optimizing-box-size"> Optimizing Box Size </h2> <p>Prior to packaging up a box, you should shrink the hard drives as much as possible. This can be done with <code>vmware-vdiskmanager</code> which is usually found in <code>/Applications/VMware Fusion.app/Contents/Library</code> for VMware Fusion. You first want to defragment then shrink the drive. Usage shown below:</p> <div class="highlight"><pre class="highlight plaintext">$ vmware-vdiskmanager -d /path/to/main.vmdk +... +$ vmware-vdiskmanager -k /path/to/main.vmdk +... +</pre></div> +<h2 id="packaging"> Packaging </h2> <p>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.</p> <div class="highlight"><pre class="highlight plaintext">$ cd /path/to/my/vm.vmwarevm +$ tar cvzf custom.box ./* +</pre></div><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/vmware/boxes.html" class="_attribution-link">https://www.vagrantup.com/docs/vmware/boxes.html</a> + </p> +</div> diff --git a/devdocs/vagrant/vmware%2Fconfiguration.html b/devdocs/vagrant/vmware%2Fconfiguration.html new file mode 100644 index 00000000..f3fb0b16 --- /dev/null +++ b/devdocs/vagrant/vmware%2Fconfiguration.html @@ -0,0 +1,39 @@ +<h1 id="configuration"> Configuration </h1> <p>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.</p> <p>Configuration settings for the provider are set in the Vagrantfile:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.vm.box = "my-box" + config.vm.provider "vmware_desktop" do |v| + v.gui = true + end +end +</pre></div> +<h2 id="provider-settings"> Provider settings </h2> <ul> <li> +<a href="#clone_directory"><code>clone_directory</code></a> (string) - Path for storing VMware clones. This value can also be set using the <code>VAGRANT_VMWARE_CLONE_DIRECTORY</code> environment variable. This defaults to <code>./.vagrant</code> </li> <li> +<a href="#enable_vmrun_ip_lookup"><code>enable_vmrun_ip_lookup</code></a> (bool) - Use vmrun to discover guest IP address. This defaults to <code>true</code> </li> <li> +<a href="#functional_hgfs"><code>functional_hgfs</code></a> (bool) - HGFS is functional within the guest. This defaults to detected capability of the guest </li> <li> +<a href="#unmount_default_hgfs"><code>unmount_default_hgfs</code></a> (bool) - Unmount the default HGFS mount point within the guest. This defaults to <code>false</code> </li> <li> +<a href="#gui"><code>gui</code></a> (bool) - Launch guest with a GUI. This defaults to <code>false</code> </li> <li> +<a href="#ssh_info_public"><code>ssh_info_public</code></a> (bool) - Use the public IP address for SSH connections to guest. This defaults to <code>false</code> </li> <li> +<a href="#verify_vmnet"><code>verify_vmnet</code></a> (bool) - Verify vmnet devices health before usage. This defaults to <code>true</code> </li> <li> +<a href="#linked_clone"><code>linked_clone</code></a> (bool) - Use linked clones instead of full copy clones. This defaults to <code>true</code> </li> <li> +<a href="#vmx"><code>vmx</code></a> (hash) - VMX key/value pairs to set or unset. If the value is <code>nil</code>, the key will be deleted. </li> <li> +<a href="#whitelist_verified"><code>whitelist_verified</code></a> (bool, symbol) - Flag that VMware box has been properly configured for whitelisted VMX settings. <code>true</code> if verified, <code>false</code> if unverified, <code>:disable_warning</code> to silence whitelist warnings. </li> <li> +<a href="#port_forward_network_pause"><code>port_forward_network_pause</code></a> - 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 <code>0</code> </li> <li> +<a href="#utility_port"><code>utility_port</code></a> (integer) - Listen port of the Vagrant VMware Utility service. This defaults to <code>9922</code> </li> <li> +<a href="#utility_certificate_path"><code>utility_certificate_path</code></a> (string) - Path to the Vagrant VMware Utility service certificates directory. The default value is dependent on the host </li> </ul> <h3 id="vm-clone-directory"> VM Clone Directory </h3> <p>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.</p> <p>The directory where the provider clones the virtual machine can be customized by setting the <code>VAGRANT_VMWARE_CLONE_DIRECTORY</code> 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.</p> <h3 id="linked-clones"> Linked Clones </h3> <p>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.</p> <p>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:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.provider "vmware_desktop" do |v| + v.linked_clone = false +end +</pre></div> +<h3 id="vmx-customization"> VMX Customization </h3> <p>If you want to add or remove specific keys from the VMX file, you can do that:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.provider "vmware_desktop" do |v| + v.vmx["custom-key"] = "value" + v.vmx["another-key"] = nil +end +</pre></div> +<p>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.</p> <p>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.</p> <p>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.</p> <p>The most common keys people look for are setting memory and CPUs. The example below sets both:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config.vm.provider "vmware_desktop" do |v| + v.vmx["memsize"] = "1024" + v.vmx["numvcpus"] = "2" +end +</pre></div><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/vmware/configuration.html" class="_attribution-link">https://www.vagrantup.com/docs/vmware/configuration.html</a> + </p> +</div> diff --git a/devdocs/vagrant/vmware%2Findex.html b/devdocs/vagrant/vmware%2Findex.html new file mode 100644 index 00000000..c1de079c --- /dev/null +++ b/devdocs/vagrant/vmware%2Findex.html @@ -0,0 +1,6 @@ +<h1 id="vmware"> VMware </h1> <p><a href="https://www.hashicorp.com">HashiCorp</a> develops an official <a href="https://www.vmware.com/products/fusion/overview.html">VMware Fusion</a> and <a href="https://www.vmware.com/products/workstation/">VMware Workstation</a> <a href="../providers/index">provider</a> for Vagrant. This provider allows Vagrant to power VMware based machines and take advantage of the improved stability and performance that VMware software offers.</p> <p>Learn more about the VMware providers on the <a href="https://www.vagrantup.com/vmware">VMware provider</a> page on the Vagrant website.</p> <p>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.</p> <p>For the most up-to-date information on compatibility and supported versions of VMware Fusion and VMware Workstation, please visit the <a href="https://www.vagrantup.com/vmware">Vagrant VMware product page</a>. Please note that VMware Fusion and VMware Workstation are third-party products that must be purchased and installed separately prior to using the provider.</p> <p>Use the navigation to the left to find a specific VMware topic to read more about.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/vmware/" class="_attribution-link">https://www.vagrantup.com/docs/vmware/</a> + </p> +</div> diff --git a/devdocs/vagrant/vmware%2Finstallation.html b/devdocs/vagrant/vmware%2Finstallation.html new file mode 100644 index 00000000..30a8a80a --- /dev/null +++ b/devdocs/vagrant/vmware%2Finstallation.html @@ -0,0 +1,24 @@ +<h1 id="installation"> Installation </h1> <p>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.</p> <p>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 <a href="https://www.vagrantup.com/vmware/downloads.html">Vagrant VMware Utility downloads page</a>.</p> <p>Next, install the Vagrant VMware provider plugin using the standard plugin installation procedure:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ vagrant plugin install vagrant-vmware-desktop +</pre></div> +<p>For more information on plugin installation, please see the <a href="../plugins/usage">Vagrant plugin usage documentation</a>.</p> <p>The Vagrant VMware plugin is a commercial product provided by <a href="https://www.hashicorp.com">HashiCorp</a> and <strong>require the purchase of a license</strong> to operate. To purchase a license, please visit the <a href="https://www.vagrantup.com/vmware#buy-now">Vagrant VMware provider</a> 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.</p> <blockquote class="alert alert-warning"> <p><strong>Warning!</strong> You cannot use your VMware product license as a Vagrant VMware plugin license. They are separate commercial products, each requiring their own license.</p> </blockquote> +<p>After installing the Vagrant VMware Desktop plugin for your system, you will need to install the license:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ vagrant plugin license vagrant-vmware-desktop ~/license.lic +</pre></div> +<p>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 <code>~/license.lic</code> 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.</p> <p>To verify the license installation, run:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ vagrant +</pre></div> +<p>If the license is not installed correctly, you will see an error message.</p> <h2 id="upgrading-to-v1-x"> Upgrading to v1.x </h2> <p>It is <strong>extremely important</strong> that the VMware plugin is upgraded to 1.0.0 or above. This release resolved critical security vulnerabilities. To learn more, please <a href="https://www.hashicorp.com/blog/introducing-the-vagrant-vmware-desktop-plugin">read our release announcement</a>.</p> <p>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.</p> <p>The path <code>~/.vagrant.d/gems/*/vagrant-vmware-{fusion,workstation}</code> should no longer exist. The gem <code>vagrant-vmware-desktop</code> 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:</p> <div class="highlight"><pre class="highlight shell" data-language="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} +</pre></div> +<h2 id="updating-the-vagrant-vmware-desktop-plugin"> Updating the Vagrant VMware Desktop plugin </h2> <p>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:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ vagrant plugin update vagrant-vmware-desktop +</pre></div> +<h2 id="frequently-asked-questions"> Frequently Asked Questions </h2> <p><strong>Q: I purchased a Vagrant VMware plugin license, but I did not receive an email?</strong><br> 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 <a href="mailto:support@hashicorp.com?subject=License%20Not%20Received">contact support</a> and include the original order number.</p> <p><strong>Q: Do I need to keep the Vagrant VMware plugin license file on disk?</strong><br> 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.</p> <p><strong>Q: I lost my original email, where can I download my Vagrant VMware plugin license again?</strong><br> Please <a href="mailto:support@hashicorp.com?subject=Lost%20My%20License&body=Hello%20support!%20I%20seem%20to%20have%20misplaced%20my%20Vagrant%20VMware%20license.%20Could%20you%20please%20send%20it%20to%20me?%20Thanks!">contact support</a>. <strong>Note:</strong> 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.</p> <p><strong>Q: I upgraded my VMware product and now my license is invalid?</strong><br> 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 <a href="https://license.hashicorp.com/upgrade/vmware">License Upgrade Center</a> and entering the email address with which they made the original purchase.</p> <p>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.</p> <p><strong>Q: Why is the Vagrant VMware plugin not working with my trial version of VMware Fusion/Workstation?</strong><br> The Vagrant VMware Fusion and Vagrant VMware Workstation plugins are not compatible with trial versions of the VMware products. We apologize for the inconvenience.</p> <p><strong>Q: How do I upgrade my currently installed Vagrant VMware plugin?</strong><br> You can update the Vagrant VMware plugin to the latest version by re-running the install command:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ vagrant plugin install vagrant-vmware-desktop +</pre></div> +<h2 id="support"> Support </h2> <p>If you have any issues purchasing, installing, or using the Vagrant VMware plugins, please <a href="mailto:support@hashicorp.com">contact support</a>. To expedite the support process, please include the <a href="../other/debugging">Vagrant debug output</a> as a Gist if applicable. This will help us more quickly diagnose your issue.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/vmware/installation.html" class="_attribution-link">https://www.vagrantup.com/docs/vmware/installation.html</a> + </p> +</div> diff --git a/devdocs/vagrant/vmware%2Fkernel-upgrade.html b/devdocs/vagrant/vmware%2Fkernel-upgrade.html new file mode 100644 index 00000000..69eacfc3 --- /dev/null +++ b/devdocs/vagrant/vmware%2Fkernel-upgrade.html @@ -0,0 +1,21 @@ +<h1 id="kernel-upgrade"> Kernel Upgrade </h1> <p>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.</p> <p>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.</p> <h2 id="enable-auto-upgrade-of-vmware-tools"> Enable Auto-Upgrade of VMware Tools </h2> <p>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:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby"># Ensure that VMWare Tools recompiles kernel modules +# when we update the linux images +$fix_vmware_tools_script = <<SCRIPT +sed -i.bak 's/answer AUTO_KMODS_ENABLED_ANSWER no/answer AUTO_KMODS_ENABLED_ANSWER yes/g' /etc/vmware-tools/locations +sed -i 's/answer AUTO_KMODS_ENABLED no/answer AUTO_KMODS_ENABLED yes/g' /etc/vmware-tools/locations +SCRIPT + +Vagrant.configure("2") do |config| + # ... + + config.vm.provision "shell", inline: $fix_vmware_tools_script +end +</pre></div> +<p>Note that this does not work for every OS, so <code>vagrant up</code> with the above settings, do a kernel upgrade, and do a <code>vagrant reload</code>. If HGFS (synced folders) and everything appears to be working, great! If not, then read on...</p> <h2 id="manually-reinstalling-vmware-tools"> Manually Reinstalling VMware Tools </h2> <p>At this point, you will have to manually reinstall VMware tools. The best source of information for how to do this is the <a href="https://kb.vmware.com/selfservice/microsites/search.do?language=en_US&cmd=displayKC&externalId=1018414">VMware documentation</a>.</p> <p>There are some gotchas:</p> <ul> <li> +<p>Make sure you have the kernel headers properly installed. This varies by distro but is generally a package available via the package manager.</p> </li> <li> +<p>Watch the installation output carefully. Even if HGFS (synced folders) support failed to build, the installer will output that installing VMware tools was successful. Read the output to find any error messages.</p> </li> </ul><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/vmware/kernel-upgrade.html" class="_attribution-link">https://www.vagrantup.com/docs/vmware/kernel-upgrade.html</a> + </p> +</div> diff --git a/devdocs/vagrant/vmware%2Fknown-issues.html b/devdocs/vagrant/vmware%2Fknown-issues.html new file mode 100644 index 00000000..ee179d50 --- /dev/null +++ b/devdocs/vagrant/vmware%2Fknown-issues.html @@ -0,0 +1,6 @@ +<h1 id="known-issues"> Known Issues </h1> <p>This page tracks some known issues or limitations of the VMware provider. Note that none of these are generally blockers to using the provider, but are good to know.</p> <h2 id="network-disconnect"> Network disconnect </h2> <p>When Vagrant applies port forwarding rules while bring up a guest instance, other running VMware VMs may experience a loss of network connectivity. The cause of this connectivity issue is the restarting of the VMware NAT service to apply new port forwarding rules. Since new rules cannot be applied to the NAT service while it is running, it is required to restart the service, which results in the loss of connectivity.</p> <h2 id="forwarded-ports-failing-in-workstation-on-windows"> Forwarded Ports Failing in Workstation on Windows </h2> <p>VMware Workstation has a bug on Windows where forwarded ports do not work properly. Vagrant actually works around this bug and makes them work. However, if you run the virtual network editor on Windows, the forwarded ports will suddenly stop working.</p> <p>In this case, run <code>vagrant reload</code> and things will begin working again.</p> <p>This issue has been reported to VMware, but a fix has not been released yet.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/vmware/known-issues.html" class="_attribution-link">https://www.vagrantup.com/docs/vmware/known-issues.html</a> + </p> +</div> diff --git a/devdocs/vagrant/vmware%2Fusage.html b/devdocs/vagrant/vmware%2Fusage.html new file mode 100644 index 00000000..1450b4d6 --- /dev/null +++ b/devdocs/vagrant/vmware%2Fusage.html @@ -0,0 +1,13 @@ +<h1 id="usage"> Usage </h1> <p>The Vagrant VMware provider is used just like any other provider. Please read the general <a href="../providers/basic_usage">basic usage</a> page for providers.</p> <p>The value to use for the <code>--provider</code> flag is <code>vmware_desktop</code>. For compatibility with older versions of the plugin, <code>vmware_fusion</code> can be used for VMware Fusion, and <code>vmware_workstation</code> for VMware Workstation.</p> <p>The Vagrant VMware provider does not support parallel execution at this time. Specifying the <code>--parallel</code> option will have no effect.</p> <p>To get started, create a new <code>Vagrantfile</code> that points to a VMware box:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby"># vagrant init hashicorp/precise64 +Vagrant.configure("2") do |config| + config.vm.box = "hashicorp/precise64" +end +</pre></div> +<p>Then run:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">$ vagrant up --provider vmware_desktop +</pre></div> +<p>This will download and bring up a new VMware Fusion/Workstation virtual machine in Vagrant.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/vmware/usage.html" class="_attribution-link">https://www.vagrantup.com/docs/vmware/usage.html</a> + </p> +</div> diff --git a/devdocs/vagrant/vmware%2Fvagrant-vmware-utility.html b/devdocs/vagrant/vmware%2Fvagrant-vmware-utility.html new file mode 100644 index 00000000..8fe34df7 --- /dev/null +++ b/devdocs/vagrant/vmware%2Fvagrant-vmware-utility.html @@ -0,0 +1,23 @@ +<h1 id="vagrant-vmware-utility-installation"> Vagrant VMware Utility Installation </h1> <h2 id="system-packages"> System Packages </h2> <p>The Vagrant VMware Utility is provided as a system package. To install the utility, download and install the correct system package from the downloads page.</p> +<center> <a class="button" href="https://www.vagrantup.com/vmware/downloads.html">Download 1.0.5</a> </center> <h2 id="manual-installation"> Manual Installation </h2> <p>If there is no officially supported system package of the utility available, it may be possible to manually install utility. This applies to Linux platforms only. First, download the latest zip package from the releases page.</p> <p>Next create a directory for the executable and unpack the executable as root.</p> <div class="highlight"><pre class="highlight shell" data-language="shell">sudo mkdir /opt/vagrant-vmware-utility/bin +sudo unzip -d /opt/vagrant-vmware-utility/bin vagrant-vmware-utility_1.0.0_x86_64.zip +</pre></div> +<p>After the executable has been installed, the utility setup tasks must be run. First, generate the required certificates:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">sudo /opt/vagrant-vmware-utility/bin/vagrant-vmware-utility certificate generate +</pre></div> +<p>The path provided from this command can be used to set the <a href="configuration#utility_certificate_path"><code>utility_certificate_path</code></a> in the Vagrantfile configuration if installing to a non-standard path.</p> <p>Finally, install the service. This will also enable the service.</p> <div class="highlight"><pre class="highlight shell" data-language="shell">sudo /usr/local/vagrant-vmware-utility/vagrant-vmware-utility service install +</pre></div> +<h1 id="usage"> Usage </h1> <p>The Vagrant VMware Utility provides the Vagrant VMware provider plugin access to various VMware functionalities. The Vagrant VMware Utility is required by the Vagrant VMware Desktop provider plugin.</p> <h2 id="vagrant-vmware-utility-access"> Vagrant VMware Utility Access </h2> <p>The Vagrant VMware Utility provides support for all users on the system using the Vagrant VMware Desktop plugin. If access restrictions to the Utility need to be applied to users on the system, this can be accomplished by restricting user access to the certificates used for connecting to the service.</p> <p>On Windows platforms these certificates can be found at:</p> <ul> <li>C:\ProgramData\HashiCorp\vagrant-vmware-desktop\certificates </li> </ul> <p>On POSIX platforms these certificates can be found at:</p> <ul> <li>/opt/vagrant-vmware-desktop/certificates </li> </ul> <h2 id="vagrant-vmware-utility-service"> Vagrant VMware Utility Service </h2> <p>The Vagrant VMware Utility consists of a small service which runs on the host platform. When the utility installer package is installed, the service is configured to automatically start. If the plugin reports errors communicating with the service, it may have stopped for some reason. The most common cause of the service not being in a running state is the VMware application not being installed. The service can be started again by using the proper command below:</p> <h3 id="windows"> Windows </h3> <p>On Windows platforms a service is created called <code>vagrant-vmware-utility</code>. The service can be manually started using the services GUI (<code>services.msc</code>) or by running the following command from a <code>cmd.exe</code> in administrator mode:</p> <div class="highlight"><pre class="highlight shell" data-language="shell">> net.exe start vagrant-vmware-utility +</pre></div> +<h3 id="macos"> macOS </h3> <div class="highlight"><pre class="highlight shell" data-language="shell">> sudo launchctl load -w /Library/LaunchDaemons/com.vagrant.vagrant-vmware-utility.plist +</pre></div> +<h3 id="linux-systemd"> Linux systemd </h3> <div class="highlight"><pre class="highlight shell" data-language="shell">> sudo systemctl start vagrant-vmware-utility +</pre></div> +<h3 id="linux-sysvinit"> Linux SysVinit </h3> <div class="highlight"><pre class="highlight shell" data-language="shell">> sudo /etc/init.d/vagrant-vmware-utility start +</pre></div> +<h3 id="linux-runit"> Linux runit </h3> <div class="highlight"><pre class="highlight shell" data-language="shell">> sudo sv start vagrant-vmware-utility +</pre></div><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/vmware/vagrant-vmware-utility.html" class="_attribution-link">https://www.vagrantup.com/docs/vmware/vagrant-vmware-utility.html</a> + </p> +</div> diff --git a/devdocs/vagrant/vmware.html b/devdocs/vagrant/vmware.html new file mode 100644 index 00000000..21fcfee4 --- /dev/null +++ b/devdocs/vagrant/vmware.html @@ -0,0 +1,6 @@ +<h1 id="vmware"> VMware </h1> <p><a href="https://www.hashicorp.com">HashiCorp</a> develops an official <a href="https://www.vmware.com/products/fusion/overview.html">VMware Fusion</a> and <a href="https://www.vmware.com/products/workstation/">VMware Workstation</a> <a href="providers/index">provider</a> for Vagrant. This provider allows Vagrant to power VMware based machines and take advantage of the improved stability and performance that VMware software offers.</p> <p>Learn more about the VMware providers on the <a href="https://www.vagrantup.com/vmware">VMware provider</a> page on the Vagrant website.</p> <p>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.</p> <p>For the most up-to-date information on compatibility and supported versions of VMware Fusion and VMware Workstation, please visit the <a href="https://www.vagrantup.com/vmware">Vagrant VMware product page</a>. Please note that VMware Fusion and VMware Workstation are third-party products that must be purchased and installed separately prior to using the provider.</p> <p>Use the navigation to the left to find a specific VMware topic to read more about.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/vmware" class="_attribution-link">https://www.vagrantup.com/docs/vmware</a> + </p> +</div> |