tnargav 1.2.3 → 1.3.3

data/website/docs/source/v2/networking/forwarded_ports.html.md

@@ -0,0 +1,57 @@
+---
+page_title: "Forwarded Ports - Networking"
+sidebar_current: "networking-fp"
+---
+
+# Forwarded Ports
+
+**Network identifier: `forwarded_port`**
+
+Forwarded ports allow you to access a port on your host machine and have
+all data forwarded to a port on the guest machine, over either TCP or UDP.
+
+For example: If the guest machine is running a web server listening on port 80,
+you can make a forwarded port mapping to port 8080 (or anything) on your host
+machine. You can then open your browser to `localhost:8080` and browse the
+website, while all actual network data is being sent to the guest.
+
+## Defining a Forwarded Port
+
+The forwarded port configuration expects two parameters, the port on the
+guest and the port on the host. Example:
+
+```ruby
+Vagrant.configure("2") do |config|
+  config.vm.network "forwarded_port", guest: 80, host: 8080
+end
+```
+
+This will allow acessing port 80 on the guest via port 8080 on the host.
+
+## Port Collisions and Correction
+
+It is common when running multiple Vagrant machines to unknowingly create
+forwarded port definitions that collide with each other (two separate
+Vagrant projects forwarded to port 8080, for example). Vagrant includes
+built-in mechanism to detect this and correct it, automatically.
+
+Port collision detection is always done. Vagrant will not allow you to
+define a forwarded port where the port on the host appears to be accepting
+traffic or connections.
+
+Port collision auto-correction must be manually enabled for each forwarded
+port, since it is often surprising when it occurs and can lead the Vagrant
+user to think that the port wasn't properly forwarded. Enabling auto correct
+is easy:
+
+```
+Vagrant.configure("2") do |config|
+  config.vm.network "forwarded_port", guest: 80, host: 8080,
+    auto_correct: true
+end
+```
+
+The final `:auto_correct` parameter set to true tells Vagrant to auto
+correct any collisions. During a `vagrant up` or `vagrant reload`, Vagrant
+will output information about any collisions detections and auto corrections
+made, so you can take notice and act accordingly.

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

@@ -0,0 +1,40 @@
+---
+page_title: "Networking"
+sidebar_current: "networking"
+---
+
+# Networking
+
+In order to access the Vagrant environment created, Vagrant exposes
+some high-level networking options for things such as forwarded ports,
+connecting to a public network, or creating a private network.
+
+The high-level networking options are meant to define an abstraction that
+works across multiple [providers](/v2/providers/index.html). This means that
+you can take your Vagrantfile you used to spin up a VirtualBox machine and
+you can reasonably expect that Vagrantfile to behave the same with something
+like VMware.
+
+You should first read the [basic usage](/v2/networking/basic_usage.html) page
+and then continue by reading the documentation for a specific networking
+primitive by following the navigation to the left.
+
+## Advanced Configuration
+
+In some cases,
+these options are _too_ high-level, and you may want to more finely tune
+and configure the network interfaces of the underlying machine. Most
+providers expose [provider-specific configuration](/v2/providers/configuration.html)
+to do this, so please read the documentation for your specific provider
+to see what options are available.
+
+<div 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>
+</div>
+

data/website/docs/source/v2/networking/private_network.html.md

@@ -0,0 +1,48 @@
+---
+page_title: "Private Networks - Networking"
+sidebar_current: "networking-private"
+---
+
+# Private Networks
+
+**Network identifier: `private_network`**
+
+Private networks allow you to access your guest machine by some address
+that is not publicly accessible from the global internet. In general, this
+means your machine gets an address in the [private address space](http://en.wikipedia.org/wiki/Private_network#Private_IPv4_address_spaces).
+
+Multiple machines within the same private network (also usually with the
+restriction that they're backed by the same [provider](/v2/providers/index.html))
+can communicate with each other on private networks.
+
+<div 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're using a particularly
+		old or new operating system that private networks won't properly
+		configure.
+	</p>
+</div>
+
+## Static IP
+
+The easiest way to use a private network is to assign a static IP to it.
+This let's you access the Vagrant managed machine using a static, known
+IP. The Vagrantfile for a static IP looks like this:
+
+```ruby
+Vagrant.configure("2") do |config|
+  config.vm.network "private_network", ip: "192.168.50.4"
+end
+```
+
+It is up to the users to make sure that the static IP doesn't collide
+with any other machines on the same network.
+
+While you can choose any IP you'd like, you _should_ use an IP from
+the [reserved private address space](http://en.wikipedia.org/wiki/Private_network#Private_IPv4_address_spaces). These IPs are guaranteed to never be publicly routable,
+and most routers actually block traffic from going to them from the
+outside world.

data/website/docs/source/v2/networking/public_network.html.md

@@ -0,0 +1,53 @@
+---
+page_title: "Public Networks - Networking"
+sidebar_current: "networking-public"
+---
+
+# Public Networks
+
+**Network identifier: `public_network`**
+
+Public networks are less private than private networks, and the exact
+meaning actually varies from [provider to provider](/v2/providers/index.html),
+hence the ambiguous definition. The idea is that while
+[private networks](/v2/networking/private_network.html) should never allow the
+general public access to your machine, public networks can.
+
+<div 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 don't support bridging generally
+		don't have any other features that map to public networks either.
+	</p>
+</div>
+
+## DHCP
+
+The easiest way to use a public network is to allow the IP to be assigned
+via DHCP. In this case, defining a public network is trivially easy:
+
+```ruby
+Vagrant.configure("2") do |config|
+  config.vm.network "public_network"
+end
+```
+
+When DHCP is used, the IP can be determined by using `vagrant ssh` to
+SSH into the machine and using the appropriate command line tool to find
+the IP, such as `ifconfig`.
+
+## Default Network Interface
+
+If more than one network interface is available on the host machine, Vagrant will
+ask you to choose which interface the virtual machine should bridge to. A default
+interface can be specified by adding a `:bridge` clause to the network definition.
+
+```ruby
+config.vm.network "public_network", :bridge => 'en1: Wi-Fi (AirPort)'
+```
+
+The string identifying the desired interface must exactly match the name of an
+available interface. If it can't be found, Vagrant will ask you to pick
+from a list of available network interfaces.

data/website/docs/source/v2/plugins/commands.html.md

@@ -0,0 +1,116 @@
+---
+page_title: "Command Plugins - Plugin Development"
+sidebar_current: "plugins-commands"
+---
+
+# Plugin Development: Commands
+
+This page documents how to add new commands to Vagrant, invokable
+via `vagrant YOUR-COMMAND`. Prior to reading this, you should be familiar
+with the [plugin development basics](/v2/plugins/development-basics.html).
+
+<div class="alert alert-warn">
+	<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>
+</div>
+
+## Definition Component
+
+Within the context of a plugin definition, new commands can be defined
+like so:
+
+```ruby
+command "foo" do
+  require_relative "command"
+  Command
+end
+```
+
+Commands are defined with the `command` method, which takes as an argument
+the name of the command, in this case "foo." This means the command will be
+invokable via `vagrant foo`. Then the block argument returns a class that
+implements the `Vagrant.plugin(2, :command)` interface.
+
+## Implementation
+
+Implementations of commands should subclass `Vagrant.plugin(2, :command)`,
+which is a Vagrant method that will return the proper superclass for
+a version 2 command. The implementation itself is quite simple, since the
+class needs to only implement a single method: `execute`. Example:
+
+```ruby
+class Command < Vagrant.plugin(2, :command)
+  def execute
+    puts "Hello!"
+    0
+  end
+end
+```
+
+The `execute` method is called when the command is invoked, and it should
+return the exit status (0 for success, anything else for error).
+
+This is a command at its simplest form. Of course, the command superclass
+gives you access to the Vagrant environment and provides some helpers to
+do common tasks such as command line parsing.
+
+## Parsing Command-Line Options
+
+The `parse_options` method is available which will parse the command line
+for you. It takes an [OptionParser](http://ruby-doc.org/stdlib-1.9.3/libdoc/optparse/rdoc/OptionParser.html)
+as an argument, and adds some common elements to it such as the `--help` flag,
+automatically showing help if requested. View the API docs directly for more
+information.
+
+This is recommended over raw parsing/manipulation of command line flags.
+The following is an example of parsing command line flags pulled directly
+from the built-in Vagrant `destroy` command:
+
+```ruby
+options = {}
+options[:force] = false
+
+opts = OptionParser.new do |o|
+  o.banner = "Usage: vagrant destroy [vm-name]"
+  o.separator ""
+
+  o.on("-f", "--force", "Destroy without confirmation.") do |f|
+    options[:force] = f
+  end
+end
+
+# Parse the options
+argv = parse_options(opts)
+```
+
+## Using Vagrant Machines
+
+The `with_target_vms` method is a helper that helps you interact with
+the machines that Vagrant manages in a standard Vagrant way. This method
+automatically does the right thing in the case of multi-machine environments,
+handling target machines on the command line (`vagrant foo my-vm`), etc.
+If you need to do any manipulation of a Vagrant machine, including SSH
+access, this helper should be used.
+
+An example of using the helper, again pulled directly from the built-in
+`destroy` command:
+
+```ruby
+with_target_vms(argv, :reverse => true) do |machine|
+  machine.action(:destroy)
+end
+```
+
+In this case, it asks for the machines in reverse order and calls the
+destroy action on each of them. If a user says `vagrant destroy foo`, then
+the helper automatically only yields the `foo` machine. If no parameter
+is given and it is a multi-machine environment, every machine in the environment
+is yielded, and so on. It just does the right thing.
+
+## Using the Raw Vagrant Environment
+
+The raw loaded `Vagrant::Environment` object is available with the
+'@env' instance variable.

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

@@ -0,0 +1,166 @@
+---
+page_title: "Custom Configuration - Plugin Development"
+sidebar_current: "plugins-configuration"
+---
+
+# Plugin Development: Configuration
+
+This page documents how to add new configuration options to Vagrant,
+settable with `config.YOURKEY` in Vagrantfiles. Prior to reading this, you should be familiar
+with the [plugin development basics](/v2/plugins/development-basics.html).
+
+<div class="alert alert-warn">
+	<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>
+</div>
+
+## Definition Component
+
+Within the context of a plugin definition, new configuration keys can be defined
+like so:
+
+```ruby
+config "foo" do
+  require_relative "config"
+  Config
+end
+```
+
+Configuration keys are defined with the `config` method, which takes as an
+argument the name of the configuration variable as the argument. This
+means that the configuration object will be accessible via `config.foo`
+in Vagrantfiles. Then, the block argument returns a class that implements
+the `Vagrant.plugin(2, :config)` interface.
+
+## Implementation
+
+Implementations of configuration keys should subclass `Vagrant.plugin(2, :config)`,
+which is a Vagrant method that will return the proper subclass for a version
+2 configuration section. The implementation is very simple, and acts mostly
+as a plain Ruby object. Here is an example:
+
+```ruby
+class Config < Vagrant.plugin(2, :config)
+  attr_accessor :widgets
+
+  def initialize
+    @widgets = UNSET_VALUE
+  end
+
+  def finalize!
+    @widgets = 0 if @widgets == UNSET_VALUE
+  end
+end
+```
+
+When using this configuration class, it looks like the following:
+
+```ruby
+Vagrant.configure("2") do |config|
+  # ...
+
+  config.foo.widgets = 12
+end
+```
+
+Easy. The only odd thing is the `UNSET_VALUE` bits above. This is actually
+so that Vagrant can properly automatically merge multiple configurations.
+Merging is covered in the next section, and `UNSET_VALUE` will be explained
+there.
+
+## Merging
+
+Vagrant works by loading [multiple Vagrantfiles and merging them](/v2/vagrantfile/index.html#load-order).
+This merge logic is built-in to configuration classes. When merging two
+configuration objects, we'll call them "old" and "new", it'll by default
+take all the instance variables defined on "new" that aren't `UNSET_VALUE`
+and set them onto the merged result.
+
+The reason `UNSET_VALUE` is used instead of Ruby's `nil` is because
+it is possible that you want the default to be some value, and the user
+actually wants to set the value to `nil`, and it is impossible for Vagrant
+to automatically determine whether the user set the instance variable, or
+if it was defaulted as nil.
+
+This merge logic is what you want almost every time. Hence, in the example
+above, `@widgets` is set to `UNSET_VALUE`. If we had two Vagrant configuration
+objects in the same file, then Vagrant would properly merge the follows.
+The example below shows this:
+
+```ruby
+Vagrant.configure("2") do |config|
+  config.widgets = 1
+end
+
+Vagrant.configure("2") do |config|
+  # ... other stuff
+end
+
+Vagrant.configure("2") do |config|
+  config.widgets = 2
+end
+```
+
+If this were placed in a Vagrantfile, after merging, the value of widgets
+would be "2".
+
+The `finalize!` method is called only once ever on the final configuration
+object in order to set defaults. If `finalize!` is called, that configuration
+will never be merged again, it is final. This lets you detect any `UNSET_VALUE`
+and set the proper default, as we do in the above example.
+
+Of course, sometimes you want custom merge logic. Let's say we
+wanted our widgets to be additive. We can override the `merge` method to
+do this:
+
+```ruby
+class Config < Vagrant.config("2", :config)
+  attr_accessor :widgets
+
+  def initialize
+    @widgets = 0
+  end
+
+  def merge(other)
+    super.tap do |result|
+      result.widgets = @widgets + other.widgets
+    end
+  end
+end
+```
+
+In this case, we didn't use `UNSET_VALUE` for widgets because we didn't
+need that behavior. We default to 0 and always merge by summing the
+two widgets. Now, if we ran the example above that had the 3 configuration
+blocks, the final value of widgets would be "3".
+
+## Validation
+
+Configuration classes are also responsible for validating their own
+values. Vagrant will call the `validate` method to do this. An example
+validation method is shown below:
+
+```ruby
+class Config < Vagrant.plugin("2", :config)
+  # ...
+
+  def validate(machine)
+    if @widgets <= 5
+      return { "foo" => ["widgets must be greater than 5"] }
+    end
+
+    {}
+  end
+end
+```
+
+The validation method is given a `machine` object, since validation is
+done for each machine that Vagrant is managing. This allows you to
+conditionally validate some keys based on the state of the machine and so on.
+
+The 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. If there are no errors, an empty hash must be returned.