tnargav 1.2.3 → 1.3.3

data/website/docs/source/v2/vagrantfile/machine_settings.html.md

@@ -0,0 +1,84 @@
+---
+page_title: "config.vm - Vagrantfile"
+sidebar_current: "vagrantfile-machine"
+---
+
+# Machine Settings
+
+**Config namespace: `config.vm`**
+
+The settings within `config.vm` modify the configuration of the
+machine that Vagrant manages.
+
+## Available Settings
+
+`config.vm.boot_timeout` - The time in seconds that Vagrant will wait
+for the machine to boot and be accessible. By default this is 300 seconds.
+
+<hr>
+
+`config.vm.box` - This configures what [box](/v2/boxes/index.html) the
+machine will be brought up against. The value here should match one of
+the installed boxes on the system.
+
+<hr>
+
+`config.vm.box_url` - The URL that the configured box can be found at.
+If the box is not installed on the system, it will be retrieved from this
+URL when `vagrant up` is run.
+
+<hr>
+
+`config.vm.graceful_halt_timeout` - The time in seconds that Vagrant will
+wait for the machine to gracefully halt when `vagrant halt` is called.
+Defaults to 300 seconds.
+
+<hr>
+
+`config.vm.guest` - The guest OS that will be running within this
+machine. This defaults to `:linux`, and Vagrant will auto-detect the
+proper distro. Vagrant needs to know this information to perform some
+guest OS-specific things such as mounting folders and configuring
+networks.
+
+<hr>
+
+`config.vm.hostname` - The hostname the machine should have. Defaults
+to nil. If nil, Vagrant won't manage the hostname. If set to a string,
+the hostname will be set on boot.
+
+<hr>
+
+`config.vm.network` - Configures [networks](/v2/networking/index.html) on
+the machine. Please see the networking page for more information.
+
+<hr>
+
+`config.vm.provider` - Configures [provider-specific configuration](/v2/providers/configuration.html),
+which is used to modify settings which are specific to a certain
+[provider](/v2/providers/index.html). If the provider you're configuring
+doesn't exist or is not setup on the system of the person who runs
+`vagrant up`, Vagrant will ignore this configuration block. This allows
+a Vagrantfile that is configured for many providers to be shared among
+a group of people who may not have all the same providers installed.
+
+<hr>
+
+`config.vm.provision` - Configures [provisioners](/v2/provisioning/index.html)
+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.
+
+<hr>
+
+`config.vm.synced_folder` - Configures [synced folders](/v2/synced-folders/index.html)
+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.
+
+<hr>
+
+`config.vm.usable_port_range` - A range of ports Vagrant can use for
+handling port collisions and such. Defaults to `2200..2250`.
+
+<hr>

data/website/docs/source/v2/vagrantfile/ssh_settings.html.md

@@ -0,0 +1,61 @@
+---
+page_title: "config.ssh - Vagrantfile"
+sidebar_current: "vagrantfile-ssh"
+---
+
+# SSH Settings
+
+**Config namespace: `config.ssh`**
+
+The settings within `config.ssh` relate to configuring how Vagrant
+will access your machine over SSH. As with most Vagrant settings, the
+defaults are typically fine, but you can fine tune whatever you'd like.
+
+## Available Settings
+
+`config.ssh.username` - 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.
+
+<hr>
+
+`config.ssh.host` - The hostname or IP to SSH into. By default this is
+empty, because the provider usually figures this out for you.
+
+<hr>
+
+`config.ssh.port` - The port to SSH into. By default this is port 22.
+
+<hr>
+
+`config.ssh.guest_port` - 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.
+
+<hr>
+
+`config.ssh.private_key_path` - 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.
+
+<hr>
+
+`config.ssh.forward_agent` - If `true`, agent forwarding over SSH
+connections is enabled. Defaults to false.
+
+<hr>
+
+`config.ssh.forward_x11` - If `true`, X11 forwarding over SSH connections
+is enabled. Defaults to false.
+
+<hr>
+
+`config.ssh.shell` - The shell to use when executing SSH commands from
+Vagrant. By default this is `bash -l`. Note that this has no effect on
+the shell you get when you run `vagrant ssh`. This configuration option
+only affects the shell to use when executing commands internally in Vagrant.

data/website/docs/source/v2/vagrantfile/vagrant_settings.html.md

@@ -0,0 +1,19 @@
+---
+page_title: "config.vagrant - Vagrantfile"
+sidebar_current: "vagrantfile-vagrant"
+---
+
+# Vagrant Settings
+
+**Config namespace: `config.vagrant`**
+
+The settings within `config.vagrant` modify the behavior of Vagrant
+itself.
+
+## Available Settings
+
+`config.vagrant.host` - This sets the type of host machine that is running
+Vagrant. By default this is `:detect`, which causes Vagrant to auto-detect
+the host. Vagrant needs to know this information in order to perform some
+host-specific things, such as preparing NFS folders if they're enabled.
+You should only manually set this if auto-detection fails.

data/website/docs/source/v2/vagrantfile/version.html.md

@@ -0,0 +1,64 @@
+---
+page_title: "Configuration Version - Vagrantfile"
+sidebar_current: "vagrantfile-version"
+---
+
+# Configuration Version
+
+Configuration versions are the mechanism by which Vagrant 1.1+ is able
+to remain [backwards compatible](v2/installation/backwards-compatibility.html)
+with Vagrant 1.0.x Vagrantfiles, while introducing dramatically new features
+and configuration options.
+
+If you run `vagrant init` today, the Vagrantfile will be in roughly the
+following format:
+
+```ruby
+VAGRANTFILE_API_VERSION = "2"
+
+Vagrant.configure(VAGRANTFILE_API_VERSION) do |config|
+  # ...
+end
+```
+
+The `"2"` in the first line above represents the version of the configuration
+object `config` that will be used for configuration for that block (the
+section between the `do` and the `end`). This object can be very
+different from version to version.
+
+Currently, there are only two supported versions: "1" and "2". Version 1
+represents the configuration from Vagrant 1.0.x. "2" represents the configuration
+for 1.1+ leading up to 2.0.x.
+
+When loading Vagrantfiles, Vagrant uses the proper configuration object
+for each version, and properly merges them, just like any other configuration.
+
+The important thing to understand as a general user of Vagrant is that
+_within a single configuration section_, only a single version can be used.
+You can't use the new `config.vm.provider` configurations in a version 1
+configuration section. Likewise, `config.vm.forwarded_port` won't work
+in a version 2 configuration section (it was renamed).
+
+If you want, you can mix and match multiple configuration versions in the
+same Vagrantfile. This is useful if you found some useful configuration
+snippet or something that you want to use. Example:
+
+```ruby
+Vagrant.configure("1") do |config|
+  # v1 configs...
+end
+
+Vagrant.configure("2") do |config|
+  # v2 configs...
+end
+```
+
+<div 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>
+</div>
+

data/website/docs/source/v2/virtualbox/boxes.html.md

@@ -0,0 +1,71 @@
+---
+page_title: "Box Format - VirtualBox Provider"
+sidebar_current: "virtualbox-boxes"
+---
+
+# Boxes
+
+As with [every provider](/v2/providers/basic_usage.html), the VirtualBox
+provider has a custom box format.
+
+This page documents the format so that you can create your own base
+boxes. Note that currently you must make these boxes by hand. A future
+release of Vagrant will provide additional mechanisms for automatically
+creating such images.
+
+<div class="alert alert-info">
+	<p>
+		<strong>Note:</strong> This is a reasonably advanced topic that
+		a beginning user of Vagrant doesn't need to understand. If you're
+		just getting started with Vagrant, skip this and use an available
+		box. If you're an experienced user of Vagrant and want to create
+		your own custom boxes, this is for you.
+	</p>
+</div>
+
+Prior to reading this page, please understand the
+[basics of the box file format](/v2/boxes/format.html).
+
+## Contents
+
+A VirtualBox base box is an archive of the resulting files of
+[exporting](http://www.virtualbox.org/manual/ch08.html#vboxmanage-export)
+a VirtualBox virtual machine. Here is an example of what is contained
+in such a box:
+
+```
+$ tree
+.
+|-- Vagrantfile
+|-- box-disk1.vmdk
+|-- box.ovf
+|-- metadata.json
+
+0 directories, 4 files
+```
+
+In addition to the files from exporting a VirtualBox VM, there is
+a "metadata.json" file used by Vagrant itself.
+
+Also, there is a "Vagrantfile." This contains some configuration to
+properly set the MAC address of the NAT network device, since VirtualBox
+requires this to be correct in order to function properly.
+
+When bringing up a VirtualBox backed machine, Vagrant
+[imports](http://www.virtualbox.org/manual/ch08.html#vboxmanage-import)
+the first "ovf" file found in the box contents.
+
+## Installed Software
+
+Base boxes for VirtualBox should have the following software installed, as
+a bare minimum:
+
+* SSH server with key-based authentication setup. If you want the box to
+  work with default Vagrant settings, the SSH user must be set to accept
+  the [insecure keypair](https://github.com/mitchellh/vagrant/blob/master/keys/vagrant.pub)
+  that ships with Vagrant.
+
+* [VirtualBox Guest Additions](http://www.virtualbox.org/manual/ch04.html) so that things such as shared
+  folders can function. There are many other benefits to installing the tools,
+  such as improved networking performance.
+

data/website/docs/source/v2/virtualbox/configuration.html.md

@@ -0,0 +1,63 @@
+---
+page_title: "Configuration - VirtualBox Provider"
+sidebar_current: "virtualbox-configuration"
+---
+
+# Configuration
+
+The VirtualBox provider exposes some additional configuration options
+that allow you to more finely control your VirtualBox-powered Vagrant
+environments.
+
+## GUI vs. Headless
+
+By default, VirtualBox machines are started in headless mode, meaning
+there is no UI for the machines visible on the host machine. Sometimes,
+you want to have a UI. Common use cases include wanting to see a browser
+that may be running in the machine, or debugging a strange boot issue.
+You can easily tell the VirtualBox provider to boot with a GUI:
+
+```
+config.vm.provider "virtualbox" do |v|
+  v.gui = true
+end
+```
+
+## Virtual Machine Name
+
+You can customize the name that appears in the VirtualBox GUI by
+setting the `name` property. By default, Vagrant sets it to the containing
+folder of the Vagrantfile plus a timestamp of when the machine was created.
+By setting another name, your VM can be more easily identified.
+
+```ruby
+config.vm.provider "virtualbox" do |v|
+  v.name = "my_vm"
+end
+```
+
+## VBoxManage Customizations
+
+[VBoxManage](http://www.virtualbox.org/manual/ch08.html) is a utility that can
+be used to make modifications to VirtualBox virtual machines from the command
+line.
+
+Vagrant exposes a way to call any command against VBoxManage just prior
+to booting the machine:
+
+```ruby
+config.vm.provider "virtualbox" do |v|
+  v.customize ["modifyvm", :id, "--cpuexecutioncap", "50"]
+end
+```
+
+In the example above, the VM is modified to have a host CPU execution
+cap of 50%, meaning that no matter how much CPU is used in the VM, no
+more than 50% would be used on your own host machine. Some details:
+
+* The `:id` special parameter is replaced with the ID of the virtual
+  machine being created, so when a VBoxManage command requires an ID, you
+  can pass this special parameter.
+
+* Multiple `customize` directives can be used. They will be executed in the
+  order given.

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

@@ -0,0 +1,21 @@
+---
+page_title: "VirtualBox Provider"
+sidebar_current: "virtualbox"
+---
+
+# VirtualBox
+
+Vagrant comes with support out of the box for [VirtualBox](http://www.virtualbox.org),
+a free, cross-platform consumer virtualization product.
+
+The VirtualBox provider is compatible with VirtualBox versions 4.0.x, 4.1.x,
+and 4.2.x. Any other version is unsupported and the provider will display
+an error message.
+
+VirtualBox must be installed on its own prior to using the provider, or
+the provider will display an error message asking you to install it.
+VirtualBox can be installed by [downloading](https://www.virtualbox.org/wiki/Downloads)
+a package or installer for your operating system and using standard procedures
+to install that package.
+
+Use the navigation to the left to find a specific VirtualBox topic to read more about.

data/website/docs/source/v2/virtualbox/usage.html.md

@@ -0,0 +1,12 @@
+---
+page_title: "Usage - VirtualBox Provider"
+sidebar_current: "virtualbox-usage"
+---
+
+# Usage
+
+The VirtualBox provider is used just like any other provider. Please
+read the general [basic usage](/v2/providers/basic_usage.html) page for
+providers.
+
+The value to use for the `--provider` flag is `virtualbox`.

data/website/docs/source/v2/vmware/boxes.html.md

@@ -0,0 +1,107 @@
+---
+page_title: "Box Format - VMware Provider"
+sidebar_current: "vmware-boxes"
+---
+
+# Boxes
+
+As with [every provider](/v2/providers/boxes.html), the VMware
+providers have a custom box format.
+
+This page documents the format so that you can create your own base boxes.
+Note that currently you must make these base boxes by hand. A future release
+of Vagrant will provide additional mechanisms for automatically creating such
+images.
+
+<div class="alert alert-info">
+	<p>
+		<strong>Note:</strong> This is a reasonably advanced topic that
+		a beginning user of Vagrant doesn't need to understand. If you're
+		just getting started with Vagrant, skip this and use an available
+		box. If you're an experienced user of Vagrant and want to create
+		your own custom boxes, this is for you.
+	</p>
+</div>
+
+Prior to reading this page, please understand the
+[basics of the box file format](/v2/boxes/format.html).
+
+## Contents
+
+A VMware base box is a compressed archive of the necessary contents
+of a VMware "vmwarevm" file. Here is an example of what is contained
+in such a box:
+
+```
+$ tree
+.
+|-- disk-s001.vmdk
+|-- disk-s002.vmdk
+|-- ...
+|-- disk.vmdk
+|-- metadata.json
+|-- precise64.nvram
+|-- precise64.vmsd
+|-- precise64.vmx
+|-- precise64.vmxf
+
+0 directories, 17 files
+```
+
+The files that are strictly required for a VMware machine to function are:
+nvram, vmsd, vmx, vmxf, and vmdk files.
+
+There is also the "metadata.json" file used by Vagrant itself. This file
+contains nothing but the defaults which are documented on the
+[box format](/v2/boxes/format.html) page.
+
+When bringing up a VMware backed machine, Vagrant copies all of the contents
+in the box into a privately managed "vmwarevm" folder, and uses the first
+"vmx" file found to control the machine.
+
+<div class="alert alert-info">
+	<h3>Linked Clones</h3>
+	<p>
+		A future version of the VMware provider will implement
+		linked cloning.
+	</p>
+</div>
+
+## Installed Software
+
+Base boxes for VMware should have the following software installed, as
+a bare minimum:
+
+* SSH server with key-based authentication setup. If you want the box to
+  work with default Vagrant settings, the SSH user must be set to accept
+  the [insecure keypair](https://github.com/mitchellh/vagrant/blob/master/keys/vagrant.pub)
+  that ships with Vagrant.
+
+* [VMware Tools](http://kb.vmware.com/kb/340) so that things such as shared
+  folders can function. There are many other benefits to installing the tools,
+  such as improved networking performance.
+
+## Optimizing Box Size
+
+Prior to packaging up a box, you should shrink the hard drives as much as
+possible. This can be done with `vmware-vdiskmanager` which is usually
+found in `/Applications/VMware Fusion.app/Contents/Library` for VMware Fusion. You first
+want to defragment then shrink the drive. Usage shown below:
+
+```
+$ vmware-vdiskmanager -d /path/to/main.vmdk
+...
+$ vmware-vdiskmanager -k /path/to/main.vmdk
+...
+```
+
+## Packaging
+
+Remove any extraneous files from the "vmwarevm" folder
+and package it. Be sure to compress the tar with gzip (done below in a
+single command) since VMware hard disks are not compressed by default.
+
+```
+$ cd /path/to/my/vm.vmwarevm
+$ tar cvzf custom.box ./*
+```