From 504d7a8accefcafc63c784573e1b59e8608f1a0b Mon Sep 17 00:00:00 2001 From: JD Harrington Date: Wed, 4 Sep 2013 18:51:56 -0400 Subject: [PATCH] Add missing Vagrantfile docs --- .../docs/source/v2/vagrantfile/index.html.md | 74 +++++++++++++++++ .../v2/vagrantfile/machine_settings.html.md | 83 +++++++++++++++++++ .../v2/vagrantfile/ssh_settings.html.md | 70 ++++++++++++++++ .../v2/vagrantfile/vagrant_settings.html.md | 18 ++++ .../source/v2/vagrantfile/version.html.md | 61 ++++++++++++++ 5 files changed, 306 insertions(+) create mode 100644 website/docs/source/v2/vagrantfile/index.html.md create mode 100644 website/docs/source/v2/vagrantfile/machine_settings.html.md create mode 100644 website/docs/source/v2/vagrantfile/ssh_settings.html.md create mode 100644 website/docs/source/v2/vagrantfile/vagrant_settings.html.md create mode 100644 website/docs/source/v2/vagrantfile/version.html.md diff --git a/website/docs/source/v2/vagrantfile/index.html.md b/website/docs/source/v2/vagrantfile/index.html.md new file mode 100644 index 000000000..2415ec314 --- /dev/null +++ b/website/docs/source/v2/vagrantfile/index.html.md @@ -0,0 +1,74 @@ +--- +sidebar_current: "vagrantfile" +--- + +# Vagrantfile + +The primary function of the Vagrantfile is to describe the type +of machine required for a project, and how to configure and +provision these machines. Vagrantfiles are called Vagrantfiles because +the actual literal filename for the file is `Vagrantfile` (casing doesn't +matter). + +Vagrant is meant to run with one Vagrantfile per project, and the Vagrantfile +is supposed to be committed to version control. This allows other developers +involved in the project to check out the code, run `vagrant up`, and be on +their way. Vagrantfiles are portable across every platform Vagrant supports. + +The syntax of Vagrantfiles is [Ruby](http://www.ruby-lang.org), but knowledge +of the Ruby programming language is not necessary to make modifications to the +Vagrantfile, since it is mostly simple variable assignment. In fact, Ruby isn't +even the most popular community Vagrant is used within, which should help show +you that despite not having Ruby knowledge, people are very successful with +Vagrant. + +## Lookup Path + +When you run any `vagrant` command, Vagrant climbs up the directory tree +looking for the first Vagrantfile it can find, starting first in the +current directory. So if you run `vagrant` in `/home/mitchellh/projects/foo`, +it will search the following paths in order for a Vagrantfile, until it +finds one: + +``` +/home/mitchellh/projects/foo/Vagrantfile +/home/mitchellh/projects/Vagrantfile +/home/mitchellh/Vagrantfile +/home/Vagrantfile +/Vagrantfile +``` + +This feature lets you run `vagrant` from any directory in your project. + +You can change the starting directory where Vagrant looks for a Vagrantfile +by setting the `VAGRANT_CWD` environmental variable to some other path. + + +## Load Order and Merging + +An important concept to understand is how Vagrant loads Vagrantfiles. Vagrant +actually loads a series of Vagrantfiles, merging the settings as it goes. This +allows Vagrantfiles of varying level of specificity to override prior settings. +Vagrantfiles are loaded in the order shown below. Note that if a Vagrantfile +is not found at any step, Vagrant continues with the next step. + +1. Built-in default Vagrantfile that ships with Vagrant. This has default + settings and should never be changed by any user of Vagrant. +2. Vagrantfile packaged with the [box](/v2/boxes.html) that is to be used + for a given machine. +3. Vagrantfile in your Vagrant home directory (defaults to `~/.vagrant.d`). + This lets you specify some defaults for your system user. +4. Vagrantfile from the project directory. This is the Vagrantfile that you'll + be modifying most of the time. + +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. + +## Available Configuration Options + +You can learn more about the available configuration options by clicking +the relevant section in the left navigational area. diff --git a/website/docs/source/v2/vagrantfile/machine_settings.html.md b/website/docs/source/v2/vagrantfile/machine_settings.html.md new file mode 100644 index 000000000..cbf004d99 --- /dev/null +++ b/website/docs/source/v2/vagrantfile/machine_settings.html.md @@ -0,0 +1,83 @@ +--- +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.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. + +
+ +`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. + +
+ +`config.vm.graceful_halt_retry_count` - The number of times to retry +gracefully shutting down the system when `vagrant halt` is called. Defaults +to 3. + +
+ +`config.vm.graceful_halt_retry_interval` - The amount of time in between +each retry of attempting to shut down, in seconds. Defaults to 1 second. + +
+ +`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. + +
+ +`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. + +
+ +`config.vm.network` - Configures [networks](/v2/networking/index.html) on +the machine. Please see the networking page for more information. + +
+ +`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. + +
+ +`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. + +
+ +`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. + +
+ +`config.vm.usable_port_range` - A range of ports Vagrant can use for +handling port collisions and such. Defaults to `2200..2250`. + +
diff --git a/website/docs/source/v2/vagrantfile/ssh_settings.html.md b/website/docs/source/v2/vagrantfile/ssh_settings.html.md new file mode 100644 index 000000000..398d535bb --- /dev/null +++ b/website/docs/source/v2/vagrantfile/ssh_settings.html.md @@ -0,0 +1,70 @@ +--- +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. + +
+ +`config.ssh.host` - The hostname or IP to SSH into. By default this is +empty, because the provider usually figures this out for you. + +
+ +`config.ssh.port` - The port to SSH into. By default this is port 22. + +
+ +`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. + +
+ +`config.ssh.max_tries` - Maximum attempts to SSH while waiting for the +machine to boot. Default is 100. + +
+ +`config.ssh.timeout` - Maximum time to wait while attempting to make +a single connection via SSH before timing out. Default is 30 seconds. + +
+ +`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. + +
+ +`config.ssh.forward_agent` - If `true`, agent forwarding over SSH +connections is enabled. Defaults to false. + +
+ +`config.ssh.forward_x11` - If `true`, X11 forwarding over SSH connections +is enabled. Defaults to false. + +
+ +`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. diff --git a/website/docs/source/v2/vagrantfile/vagrant_settings.html.md b/website/docs/source/v2/vagrantfile/vagrant_settings.html.md new file mode 100644 index 000000000..768bc29eb --- /dev/null +++ b/website/docs/source/v2/vagrantfile/vagrant_settings.html.md @@ -0,0 +1,18 @@ +--- +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. diff --git a/website/docs/source/v2/vagrantfile/version.html.md b/website/docs/source/v2/vagrantfile/version.html.md new file mode 100644 index 000000000..9049fbe99 --- /dev/null +++ b/website/docs/source/v2/vagrantfile/version.html.md @@ -0,0 +1,61 @@ +--- +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 Vagranfile will be in roughly the +following format: + +```ruby +Vagrant.configure("2") do |config| + # ... +end +``` + +The `"2"` in the first line above represents the version of the configuration +object `config` that will be used for configuration for that block (the +section between the `do` and the `end`). This object can be very +different from version to version. + +Currently, there are only two supported versions: "1" and "2". Version 1 +represents the configuration from Vagrant 1.0.x. "2" represents the configuration +for 1.1+ leading up to 2.0.x. + +When loading Vagrantfiles, Vagrant uses the proper configuration object +for each version, and properly merges them, just like any other configuration. + +The important thing to understand as a general user of Vagrant is that +_within a single configuration section_, only a single version can be used. +You 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 +``` + +
+

+ What is Vagrant::Config.run? + You may see this in Vagrantfiles. This was actually how Vagrant 1.0.x + did configuration. In Vagrant 1.1+, this is synonymous with + Vagrant.configure("1"). +

+
+