tnargav 1.2.3 → 1.3.3

data/website/docs/source/v2/providers/custom.html.md

@@ -0,0 +1,9 @@
+---
+page_title: "Custom Provider - Providers"
+sidebar_current: "providers-custom"
+---
+
+# Custom Provider
+
+To learn how to make your own custom providers, read the plugin development
+guide on [creating custom providers](/v2/plugins/providers.html).

data/website/docs/source/v2/providers/default.html.md

@@ -0,0 +1,22 @@
+---
+page_title: "Default Provider - Providers"
+sidebar_current: "providers-default"
+---
+
+# Default Provider
+
+By default, VirtualBox is the default provider for Vagrant. VirtualBox is
+still the most accessible platform to use Vagrant: it is free, cross-platform,
+and has been supported by Vagrant for years. With VirtualBox as the default
+provider, it provides the lowest friction for new users to get started with
+Vagrant.
+
+However, you may find after using Vagrant for some time that you prefer
+to use another provider as your default. In fact, this is quite common.
+To make this experience better, Vagrant allows specifying the default
+provider to use by setting the `VAGRANT_DEFAULT_PROVIDER` environmental
+variable.
+
+Just set `VAGRANT_DEFAULT_PROVIDER` to the provider you wish to be the
+default. For example, if you use Vagrant with VMware Fusion, you can set
+the environmental variable to `vmware_fusion` and it will be your default.

data/website/docs/source/v2/providers/index.html.md

@@ -0,0 +1,23 @@
+---
+page_title: "Providers"
+sidebar_current: "providers"
+---
+
+# Providers
+
+While Vagrant ships out of the box with support for [VirtualBox](http://www.virtualbox.org),
+Vagrant has the ability to manage other types of machines as well. This is done
+by using other _providers_ with Vagrant.
+
+Alternate providers can offer different features that make more sense in your use case.
+For example, if you're using Vagrant for any real work, [VMware](http://www.vmware.com)
+providers are recommended since they're well supported and generally more
+stable and performant than VirtualBox.
+
+Before you can use another provider, you must install it. Vagrant only ships
+with VirtualBox support. Installation of other providers is done via the
+Vagrant plugin system.
+
+Once the provider is installed, usage is straightforward and simple, as
+you would expect with Vagrant. Read into the relevant subsections found in
+the navigation to the left for more information.

data/website/docs/source/v2/providers/installation.html.md

@@ -0,0 +1,11 @@
+---
+page_title: "Installation - Providers"
+sidebar_current: "providers-installation"
+---
+
+# Provider Installation
+
+Providers are distributed as Vagrant plugins, and are therefore installed
+using [standard plugin installation steps](/v2/plugins/usage.html). After
+installing a plugin which contains a provider, the provider should
+immediately be available.

data/website/docs/source/v2/provisioning/ansible.html.md

@@ -0,0 +1,144 @@
+---
+page_title: "Ansible - Provisioning"
+sidebar_current: "provisioning-ansible"
+---
+
+# Ansible Provisioner
+
+**Provisioner name: `"ansible"`**
+
+The ansible provisioner allows you to provision the guest using
+[Ansible](http://ansible.cc) playbooks.
+
+Ansible playbooks are [YAML](http://en.wikipedia.org/wiki/YAML) documents that
+comprise the set of steps to be orchestrated on one or more machines. 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
+a single page of documentation.
+
+<div class="alert alert-warn">
+  <p>
+    <strong>Warning:</strong> If you're not familiar with Ansible and Vagrant already,
+    I recommend starting with the <a href="/v2/provisioning/shell.html">shell
+    provisioner</a>. However, if you're comfortable with Vagrant already, Vagrant
+    is a great way to learn Ansible.
+  </p>
+</div>
+
+## Inventory File
+
+When using Ansible, it needs to know on which machines a given playbook should run. It does
+this by way of an inventory file which lists those machines. In the context of Vagrant,
+there are two ways to approach working with inventory files. The first and simplest option
+is to not provide one to Vagrant at all. Vagrant will generate inventory files for each
+virtual machine it manages, and use them for provisioning machines. Generated inventory files
+are created adjacent to your Vagrantfile, named using the machine names set in your Vagrantfile.
+
+The second option is for situations where you'd like to have more than one virtual machine
+in a single inventory file, perhaps leveraging more complex playbooks or inventory grouping.
+If you provide the `ansible.inventory_path` option referencing a specific inventory file
+dedicated to your Vagrant project, that one will be used instead of generating them.
+Such an inventory file for use with Vagrant might look like:
+
+```
+[vagrant]
+192.168.111.222
+```
+
+Where the above IP address is one set in your Vagrantfile:
+
+```
+config.vm.network :private_network, ip: "192.168.111.222"
+```
+
+## Playbook
+
+The second component of a successful Ansible provisioner setup is the Ansible playbook
+which contains the steps that should be run on the guest. Ansible's
+[playbook documentation](http://ansible.cc/docs/playbooks.html) goes into great
+detail on how to author playbooks, and there are a number of
+[best practices](http://ansible.cc/docs/bestpractices.html) that can be applied to use
+Ansible's powerful features effectively. A playbook that installs and starts (or restarts
+if it was updated) the NTP daemon via YUM looks like:
+
+```
+---
+- hosts: all
+  tasks:
+    - name: ensure ntpd is at the latest version
+      yum: pkg=ntp state=latest
+      notify:
+      - restart ntpd
+  handlers:
+    - name: restart ntpd
+      service: name=ntpd state=restarted
+```
+
+You can of course target other operating systems that don't have YUM by changing the
+playbook tasks. Ansible ships with a number of [modules](http://ansible.cc/docs/modules.html)
+that make running otherwise tedious tasks dead simple.
+
+## Running Ansible
+
+To run Ansible against your Vagrant guest, the basic Vagrantfile configuration looks like:
+
+```ruby
+Vagrant.configure("2") do |config|
+  config.vm.provision "ansible" do |ansible|
+    ansible.playbook = "playbook.yml"
+  end
+end
+```
+
+This causes Vagrant to run the `playbook.yml` playbook against all hosts in the inventory file.
+Since an Ansible playbook can include many files, you may also collect the related files in
+a directory structure like this:
+
+```
+$ tree
+.
+|-- Vagrantfile
+|-- provisioning
+|   |-- group_vars
+|           |-- all
+|   |-- playbook.yml
+```
+
+In such an arrangement, the `ansible.playbook` path should be adjusted accordingly:
+
+```ruby
+Vagrant.configure("2") do |config|
+  config.vm.provision "ansible" do |ansible|
+    ansible.playbook = "provisioning/playbook.yml"
+  end
+end
+```
+
+## Additional Options
+
+The Ansible provisioner also includes a number of additional options that can be set,
+all of which get passed to the `ansible-playbook` command that ships with Ansible.
+
+* `ansible.extra_vars` can be used to pass a hash of additional variables to the playbook. For example:
+```
+ansible.extra_vars = {
+  ntp_server: "pool.ntp.org",
+  nginx_workers: 4
+}
+```
+These variables take the highest precedence over any other variables.
+* `ansible.sudo` can be set to `true` to cause Ansible to perform commands using sudo.
+* `ansible.sudo_user` can be set to a string containing a username on the guest who should be used
+by the sudo command.
+* `ansible.ask_sudo_pass` can be set to `true` to require Ansible to prompt for a sudo password.
+* `ansible.limit` can be set to a string or an array of machines or groups from the inventory file to further narrow down which hosts are affected.
+* `ansible.verbose` can be set to increase Ansible's verbosity to obtain full detailed logging. By default, Vagrant uses Ansible default verbosity (`--verbose` or `-v`). By enabling this option following higher verbosity can be activated:
+  * `'vv'`
+  * `'vvv'`, also aliased as `'extra'`
+* `ansible.tags` can be set to a string or an array of tags. Only plays, roles and tasks tagged with these values will be executed.
+* `ansible.skip_tags` can be set to a string or an array of tags. Only plays, roles and tasks that *do not match* these values will be executed.
+* `ansible.start_at_task` can be set to a string corresponding to the task name where the playbook provision will start.
+* `ansible.raw_arguments` is an *unsafe wildcard* string that can be used to take advantage of `ansible-playbook` arguments that are not (yet) supported by this Vagrant provisioner plugin. This can be very useful when integrating with bleeding edge Ansible versions. Following precedence rules apply:
+  * Any supported options (described above) will override conflicting `raw_arguments` value (e.g. `--tags` or `--start-at-task`)
+  * Vagrant default user authentication can be overridden via `raw_arguments` (with custom values for `--user` and `--private-key`)
+* `ansible.host_key_checking` can be set to `false` which will disable host key checking and prevent `"FAILED: (25, 'Inappropriate ioctl for device')"` errors from being reported during provisioner runs.  The default value is `true`, which matches the default behavior of Ansible 1.2.1 and later.

data/website/docs/source/v2/provisioning/basic_usage.html.md

@@ -0,0 +1,67 @@
+---
+page_title: "Basic Usage - Provisioning"
+sidebar_current: "provisioning-basic"
+---
+
+# Basic Usage of Provisioners
+
+While Vagrant offers multiple options for how you are able to provision
+your machine, there is a standard usage pattern as well as some important
+points common to all provisioners that are important to know.
+
+## Configuration
+
+First, every provisioner is configured within your [Vagrantfile](/v2/vagrantfile/index.html)
+using the `config.vm.provision` method call. For example, the Vagrantfile
+below enables shell provisioning:
+
+```ruby
+Vagrant.configure("2") do |config|
+  # ... other configuration
+
+  config.vm.provision "shell", inline: "echo hello"
+end
+```
+
+Every provisioner has an identifier, such as `"shell", used as the first
+parameter to the provisioning configuration. Following that is basic key/value
+for configuring that specific provisioner. Instead of basic key/value, you
+can also use a Ruby block for a syntax that is more like variable assignment.
+The following is effectively the same as the prior example:
+
+```ruby
+Vagrant.configure("2") do |config|
+  # ... other configuration
+
+  config.vm.provision "shell" do |s|
+    s.inline = "echo hello"
+  end
+end
+```
+
+The benefit of the block-based syntax is that with more than a couple options
+it can greatly improve readability. Additionally, some provisioners, like
+the Chef provisioner, have special methods that can be called within that
+block to ease configuration that can't be done with the key/value approach.
+
+## Multiple Provisioners
+
+Multiple `config.vm.provision` methods can be used to define multiple
+provisioners. These provisioners will be run in the order they're defined.
+This is useful for a variety of reasons, but most commonly it is used so
+that a shell script can bootstrap some of the system so that another provisioner
+can take over later.
+
+## Running Provisioners
+
+Provisioners are run in three cases: `vagrant up`, `vagrant reload`, and
+`vagrant provision`.
+
+A `--no-provision` flag can be passed to `up` and `reload` if you don't
+want to run provisioners. Likewise, you can pass `--provision` to force
+provisioning.
+
+The `--provision-with` flag can be used if you only want to run a
+specific provisioner if you have multiple provisioners specified. For
+example, if you have a shell and Puppet provisioner and only want to
+run the shell one, you can do `vagrant provision --provision-with shell`.

data/website/docs/source/v2/provisioning/chef_client.html.md

@@ -0,0 +1,109 @@
+---
+page_title: "Chef Client - Provisioning"
+sidebar_current: "provisioning-chefclient"
+---
+
+# Chef Client Provisioner
+
+**Provisioner name: `chef_client`**
+
+The chef client provisioner allows you to provision the guest using
+[Chef](http://www.opscode.com/chef/), specifically by connecting
+to an existing Chef Server and registering the Vagrant machine as a
+node within your infrastructure.
+
+If you're just learning Chef for the first time, you probably want
+to start with the [Chef Solo](/v2/provisioning/chef_solo.html)
+provisioner.
+
+<div class="alert alert-warn">
+	<p>
+		<strong>Warning:</strong> If you're not familiar with Chef and Vagrant already,
+		I recommend starting with the <a href="/v2/provisioning/shell.html">shell
+		provisioner</a>.
+	</p>
+</div>
+
+## Authenticating
+
+The minimum required to use provision using Chef client is to provide
+a URL to the Chef sever as well as the path to the validation key so
+that the node can register with the Chef server:
+
+```ruby
+Vagrant.configure("2") do |config|
+  config.vm.provision "chef_client" do |chef|
+    chef.chef_server_url = "http://mychefserver.com:4000/"
+    chef.validation_key_path = "validation.pem"
+  end
+end
+```
+
+The node will register with the Chef server specified, download the
+proper run list for that node, and provision.
+
+## Specifying a Run List
+
+Normally, the Chef server is responsible for specifying the run list
+for the node. However, you can override what the Chef server sends
+down by manually specifying a run list:
+
+```ruby
+Vagrant.configure("2") do |config|
+  config.vm.provision "chef_client" do |chef|
+    # Add a recipe
+    chef.add_recipe "apache"
+
+    # Or maybe a role
+    chef.add_role "web"
+  end
+end
+```
+
+Remember, this will _override_ the run list specified on the Chef
+server itself.
+
+## Environments
+
+You can specify the [environment](http://wiki.opscode.com/display/chef/Environments)
+for the node to come up in using the `environment` configuration option:
+
+```ruby
+Vagrant.configure("2") do |config|
+  config.vm.provision "chef_client" do |chef|
+    # ...
+
+    chef.environment = "development"
+  end
+end
+```
+
+## Other Configuration Options
+
+There are a few more configuration options available. These generally don't
+need to be modified but are available if your Chef server requires customization
+of these variables:
+
+* `client_key_path`
+* `node_name`
+* `validation_client_name`
+
+## Cleanup
+
+When you provision your Vagrant virtual machine with Chef server, it creates a
+new Chef "node" entry and Chef "client" entry on the Chef server, using the
+hostname of the machine. After you tear down your guest machine, you must
+explicitly delete these entries from the Chef server before you provision
+a new one with Chef server. For example, using Chef's built-in `knife` tool:
+
+```
+$ knife node delete precise64
+$ knife client delete precise64
+```
+
+If you fail to do so, you'll get the following error when Vagrant
+tries to provision the machine with Chef client:
+
+```
+HTTP Request Returned 409 Conflict: Client already exists.
+```

data/website/docs/source/v2/provisioning/chef_solo.html.md

@@ -0,0 +1,156 @@
+---
+page_title: "Chef Solo - Provisioning"
+sidebar_current: "provisioning-chefsolo"
+---
+
+# Chef Solo Provisioner
+
+**Provisioner name: `chef_solo`**
+
+The chef solo provisioner allows you to provision the guest using
+[Chef](http://www.opscode.com/chef/), specifically with
+[Chef Solo](http://docs.opscode.com/chef_solo.html).
+
+Chef solo is ideal for people who are already experienced with Chef,
+already have Chef cookbooks, or are looking to learn Chef. Specifically,
+this documentation page will not go into how to use Chef or how to write
+Chef cookbooks, since Chef is a complete system that is beyond the scope
+of a single page of documentation.
+
+<div class="alert alert-warn">
+	<p>
+		<strong>Warning:</strong> If you're not familiar with Chef and Vagrant already,
+		I recommend starting with the <a href="/v2/provisioning/shell.html">shell
+		provisioner</a>. However, if you're comfortable with Vagrant already, Vagrant
+		is the best way to learn Chef.
+	</p>
+</div>
+
+
+## Specifying a Run List
+
+The easiest way to get started with the Chef Solo provisioner is to just
+specify a [run list](http://docs.opscode.com/essentials_node_object_run_lists.html). This looks like:
+
+```ruby
+Vagrant.configure("2") do |config|
+  config.vm.provision "chef_solo" do |chef|
+    chef.add_recipe "apache"
+  end
+end
+```
+
+This causes Vagrant to run Chef Solo with the "apache" cookbook. The cookbooks
+by default are looked for in the "cookbooks" directory relative to your
+project root. The directory structure ends up looking like this:
+
+```
+$ tree
+.
+|-- Vagrantfile
+|-- cookbooks
+|   |-- apache
+|       |-- recipes
+|           |-- default.rb
+```
+
+## Custom Cookbooks Path
+
+Instead of using the default "cookbooks" directory, a custom cookbooks
+path can also be set via the `cookbooks_path` configuration directive:
+
+```ruby
+Vagrant.configure("2") do |config|
+  config.vm.provision "chef_solo" do |chef|
+    chef.cookbooks_path = "my_cookbooks"
+  end
+end
+```
+
+The path can be relative or absolute. If it is relative, it is relative
+to the project root.
+
+The configuration value can also be an array of paths:
+
+```ruby
+Vagrant.configure("2") do |config|
+  config.vm.provision "chef_solo" do |chef|
+    chef.cookbooks_path = ["cookbooks", "my_cookbooks"]
+  end
+end
+```
+
+## Roles
+
+Vagrant also supports provisioning with [Chef roles](http://docs.opscode.com/essentials_roles.html).
+This is done by specifying a path to a roles folder where roles are defined
+and by adding roles to your run list:
+
+```ruby
+Vagrant.configure("2") do |config|
+  config.vm.provision "chef_solo" do |chef|
+    chef.roles_path = "roles"
+    chef.add_role("web")
+  end
+end
+```
+
+Just like the cookbooks path, the roles path is relative to the project
+root if a relative path is given.
+
+**Note:** The name of the role file must be the same as the role name.
+For example the `web` role must be in the `roles_path` as web.json or web.rb.
+This is required by Chef itself, and isn't a limitation imposed by
+Vagrant.
+
+## Data Bags
+
+[Data bags](http://docs.opscode.com/essentials_data_bags.html) are also
+supported by the Chef Solo provisioner. This is done by specifying
+a path to your data bags directory:
+
+```ruby
+Vagrant.configure("2") do |config|
+  config.vm.provision "chef_solo" do |chef|
+    chef.data_bags_path = "data_bags"
+  end
+end
+```
+
+## Custom JSON Data
+
+Additional configuration data for Chef attributes can be passed in
+to Chef solo. This is done by setting the `json` property with a Ruby
+hash (dictionary-like object), which is converted to JSON and passed
+in to Chef:
+
+```
+Vagrant.configure("2") do |config|
+  config.vm.provision "chef_solo" do |chef|
+    # ...
+
+    chef.json = {
+      "apache" => {
+        "listen_address" => "0.0.0.0"
+      }
+    }
+  end
+end
+```
+
+Hashes, arrays, etc. can be used with the JSON configuration object. Basically,
+anything that can be turned cleanly into JSON works.
+
+## Custom Node Name
+
+You can specify a custom node name by setting the `node_name` property. This
+is useful for cookbooks that may depend on this being set to some sort
+of value. Example:
+
+```ruby
+Vagrant.configure("2") do |config|
+  config.vm.provision "chef_solo" do |chef|
+    chef.node_name = "foo"
+  end
+end
+```