Module: Vagrant

Defined in:
lib/vagrant/errors.rb,
lib/vagrant.rb,
lib/vagrant/ui.rb,
lib/vagrant/box.rb,
lib/vagrant/cli.rb,
lib/vagrant/util.rb,
lib/vagrant/host.rb,
lib/vagrant/guest.rb,
lib/vagrant/plugin.rb,
lib/vagrant/config.rb,
lib/vagrant/action.rb,
lib/vagrant/util/io.rb,
lib/vagrant/bundler.rb,
lib/vagrant/version.rb,
lib/vagrant/machine.rb,
lib/vagrant/util/ssh.rb,
lib/vagrant/registry.rb,
lib/vagrant/plugin/v1.rb,
lib/vagrant/util/busy.rb,
lib/vagrant/plugin/v2.rb,
lib/vagrant/config/v1.rb,
lib/vagrant/config/v2.rb,
lib/vagrant/util/which.rb,
lib/vagrant/environment.rb,
lib/vagrant/action/hook.rb,
lib/vagrant/vagrantfile.rb,
lib/vagrant/batch_action.rb,
lib/vagrant/util/counter.rb,
lib/vagrant/box_metadata.rb,
lib/vagrant/action/warden.rb,
lib/vagrant/action/runner.rb,
lib/vagrant/config/loader.rb,
lib/vagrant/machine_state.rb,
lib/vagrant/util/platform.rb,
lib/vagrant/machine_index.rb,
lib/vagrant/util/retryable.rb,
lib/vagrant/shared_helpers.rb,
lib/vagrant/action/builder.rb,
lib/vagrant/plugin/v1/host.rb,
lib/vagrant/util/safe_exec.rb,
lib/vagrant/util/file_mode.rb,
lib/vagrant/config/v2/util.rb,
lib/vagrant/config/v2/root.rb,
lib/vagrant/util/safe_puts.rb,
lib/vagrant/plugin/v2/host.rb,
lib/vagrant/plugin/manager.rb,
lib/vagrant/box_collection.rb,
lib/vagrant/config/v1/root.rb,
lib/vagrant/plugin/v2/guest.rb,
lib/vagrant/util/deep_merge.rb,
lib/vagrant/util/subprocess.rb,
lib/vagrant/util/network_ip.rb,
lib/vagrant/util/safe_chdir.rb,
lib/vagrant/plugin/v1/guest.rb,
lib/vagrant/util/downloader.rb,
lib/vagrant/util/powershell.rb,
lib/vagrant/capability_host.rb,
lib/vagrant/plugin/v1/plugin.rb,
lib/vagrant/plugin/v1/config.rb,
lib/vagrant/config/v2/loader.rb,
lib/vagrant/config/v1/loader.rb,
lib/vagrant/util/shell_quote.rb,
lib/vagrant/plugin/v2/config.rb,
lib/vagrant/plugin/v2/errors.rb,
lib/vagrant/plugin/v1/errors.rb,
lib/vagrant/plugin/v2/plugin.rb,
lib/vagrant/plugin/v2/manager.rb,
lib/vagrant/plugin/v1/command.rb,
lib/vagrant/plugin/state_file.rb,
lib/vagrant/util/is_port_open.rb,
lib/vagrant/plugin/v1/manager.rb,
lib/vagrant/plugin/v2/command.rb,
lib/vagrant/plugin/v2/provider.rb,
lib/vagrant/plugin/v1/provider.rb,
lib/vagrant/action/builtin/lock.rb,
lib/vagrant/config/version_base.rb,
lib/vagrant/action/builtin/call.rb,
lib/vagrant/plugin/v2/components.rb,
lib/vagrant/plugin/v2/provisioner.rb,
lib/vagrant/plugin/v1/provisioner.rb,
lib/vagrant/util/silence_warnings.rb,
lib/vagrant/plugin/v1/communicator.rb,
lib/vagrant/action/builtin/box_add.rb,
lib/vagrant/action/builtin/confirm.rb,
lib/vagrant/action/builtin/message.rb,
lib/vagrant/action/general/package.rb,
lib/vagrant/action/builtin/env_set.rb,
lib/vagrant/config/v2/dummy_config.rb,
lib/vagrant/action/builtin/ssh_run.rb,
lib/vagrant/util/template_renderer.rb,
lib/vagrant/config/v1/dummy_config.rb,
lib/vagrant/plugin/v2/communicator.rb,
lib/vagrant/action/builtin/ssh_exec.rb,
lib/vagrant/plugin/v2/synced_folder.rb,
lib/vagrant/action/builtin/is_state.rb,
lib/vagrant/util/string_block_editor.rb,
lib/vagrant/util/stacked_proc_runner.rb,
lib/vagrant/action/builtin/provision.rb,
lib/vagrant/util/line_ending_helpers.rb,
lib/vagrant/action/builtin/handle_box.rb,
lib/vagrant/util/scoped_hash_override.rb,
lib/vagrant/action/builtin/box_remove.rb,
lib/vagrant/action/builtin/box_update.rb,
lib/vagrant/action/builtin/set_hostname.rb,
lib/vagrant/action/builtin/graceful_halt.rb,
lib/vagrant/util/ansi_escape_code_remover.rb,
lib/vagrant/action/builtin/synced_folders.rb,
lib/vagrant/action/builtin/handle_box_url.rb,
lib/vagrant/action/builtin/destroy_confirm.rb,
lib/vagrant/action/builtin/config_validate.rb,
lib/vagrant/action/builtin/box_check_outdated.rb,
lib/vagrant/action/builtin/mixin_provisioners.rb,
lib/vagrant/util/hash_with_indifferent_access.rb,
lib/vagrant/action/builtin/provisioner_cleanup.rb,
lib/vagrant/action/builtin/mixin_synced_folders.rb,
lib/vagrant/action/builtin/synced_folder_cleanup.rb,
lib/vagrant/action/builtin/wait_for_communicator.rb,
lib/vagrant/action/builtin/handle_forwarded_port_collisions.rb

Overview

This file contains all the errors that the V1 plugin interface may throw.

Defined Under Namespace

Modules: Action, CapabilityHost, Config, Errors, Plugin, UI, Util Classes: BatchAction, Box, BoxCollection, BoxMetadata, Bundler, CLI, Environment, Guest, Host, Machine, MachineIndex, MachineState, Registry, Vagrantfile

Constant Summary

PLUGIN_COMPONENTS =

These are the various plugin versions and their components in a lazy loaded Hash-like structure.

Registry.new.tap do |c|
  c.register(:1")                  { Plugin::V1::Plugin }
  c.register([:1", :command])      { Plugin::V1::Command }
  c.register([:1", :communicator]) { Plugin::V1::Communicator }
  c.register([:1", :config])       { Plugin::V1::Config }
  c.register([:1", :guest])        { Plugin::V1::Guest }
  c.register([:1", :host])         { Plugin::V1::Host }
  c.register([:1", :provider])     { Plugin::V1::Provider }
  c.register([:1", :provisioner])  { Plugin::V1::Provisioner }

  c.register(:2")                  { Plugin::V2::Plugin }
  c.register([:2", :command])      { Plugin::V2::Command }
  c.register([:2", :communicator]) { Plugin::V2::Communicator }
  c.register([:2", :config])       { Plugin::V2::Config }
  c.register([:2", :guest])        { Plugin::V2::Guest }
  c.register([:2", :host])         { Plugin::V2::Host }
  c.register([:2", :provider])     { Plugin::V2::Provider }
  c.register([:2", :provisioner])  { Plugin::V2::Provisioner }
  c.register([:2", :synced_folder]) { Plugin::V2::SyncedFolder }
end
VERSION =

This will always be up to date with the current version of Vagrant, since it is used to generate the gemspec and is also the source of the version for vagrant -v

File.read(
File.expand_path("../../../version.txt", __FILE__)).chomp
DEFAULT_SERVER_URL =

This is the default endpoint of the Vagrant Cloud in use. API calls will be made to this for various functions of Vagrant that may require remote access.

Returns:

  • (String)
"https://vagrantcloud.com"

Class Method Summary (collapse)

Class Method Details

+ (Object) configure(version, &block)

Configure a Vagrant environment. The version specifies the version of the configuration that is expected by the block. The block, based on that version, configures the environment.

Note that the block isn't run immediately. Instead, the configuration block is stored until later, and is run when an environment is loaded.

Parameters:

  • version (String)

    Version of the configuration



137
138
139
# File 'lib/vagrant.rb', line 137

def self.configure(version, &block)
  Config.run(version, &block)
end

+ (Boolean) has_plugin?(name)

This checks if a plugin with the given name is installed. This can be used from the Vagrantfile to easily branch based on plugin availability.

Returns:

  • (Boolean)


144
145
146
147
148
149
150
151
# File 'lib/vagrant.rb', line 144

def self.has_plugin?(name)
  # We check the plugin names first because those are cheaper to check
  return true if plugin("2").manager.registered.any? { |p| p.name == name }

  # Now check the plugin gem names
  require "vagrant/plugin/manager"
  Plugin::Manager.instance.installed_specs.any? { |s| s.name == name }
end

+ (Boolean) in_installer?

This returns a true/false showing whether we're running from the environment setup by the Vagrant installers.

Returns:

  • (Boolean)


16
17
18
# File 'lib/vagrant/shared_helpers.rb', line 16

def self.in_installer?
  !!ENV["VAGRANT_INSTALLER_ENV"]
end

+ (String) installer_embedded_dir

Returns the path to the embedded directory of the Vagrant installer, if there is one (if we're running in an installer).

Returns:

  • (String)


24
25
26
27
# File 'lib/vagrant/shared_helpers.rb', line 24

def self.installer_embedded_dir
  return nil if !Vagrant.in_installer?
  ENV["VAGRANT_INSTALLER_EMBEDDED_DIR"]
end

+ (String) latest_version

Returns the latest version of Vagrant that is available.

This makes an HTTP call.

Returns:

  • (String)


34
35
36
37
38
39
40
41
42
43
44
# File 'lib/vagrant/shared_helpers.rb', line 34

def self.latest_version
  # Lazy-require this so that the overhead of this file is low
  require "vagrant/util/downloader"

  tf  = Tempfile.new("vagrant")
  tf.close
  url = "http://www.vagrantup.com/latest-version.json"
  Vagrant::Util::Downloader.new(url, tf.path).download!
  data = JSON.parse(File.read(tf.path))
  data["version"]
end

+ (Class) plugin(version, component = nil)

Returns a superclass to use when creating a plugin for Vagrant. Given a specific version, this returns a proper superclass to use to register plugins for that version.

Optionally, if you give a specific component, then it will return the proper superclass for that component as well.

Plugins and plugin components should subclass the classes returned by this method. This method lets Vagrant core control these superclasses and change them over time without affecting plugins. For example, if the V1 superclass happens to be "Vagrant::V1," future versions of Vagrant may move it to "Vagrant::Plugins::V1" and plugins will not be affected.

Parameters:

  • version (String)
  • component (String) (defaults to: nil)

Returns:

  • (Class)

Raises:

  • (ArgumentError)


170
171
172
173
174
175
176
177
178
179
180
181
182
183
# File 'lib/vagrant.rb', line 170

def self.plugin(version, component=nil)
  # Build up the key and return a result
  key    = version.to_s.to_sym
  key    = [key, component.to_s.to_sym] if component
  result = PLUGIN_COMPONENTS.get(key)

  # If we found our component then we return that
  return result if result

  # If we didn't find a result, then raise an exception, depending
  # on if we got a component or not.
  raise ArgumentError, "Plugin superclass not found for version/component: " +
    "#{version} #{component}"
end

+ (Boolean) plugins_enabled?

This returns whether or not 3rd party plugins should be loaded.

Returns:

  • (Boolean)


49
50
51
# File 'lib/vagrant/shared_helpers.rb', line 49

def self.plugins_enabled?
  !ENV["VAGRANT_NO_PLUGINS"]
end

+ (Object) require_plugin(name)

Deprecated.


186
187
188
189
190
# File 'lib/vagrant.rb', line 186

def self.require_plugin(name)
  puts "Vagrant.require_plugin is deprecated and has no effect any longer."
  puts "Use `vagrant plugin` commands to manage plugins. This warning will"
  puts "be removed in the next version of Vagrant."
end

+ (Object) require_version(*requirements)

This allows a Vagrantfile to specify the version of Vagrant that is required. You can specify a list of requirements which will all be checked against the running Vagrant version.

This should be specified at the top of any Vagrantfile.

Examples are shown below:

Vagrant.require_version(">= 1.3.5") Vagrant.require_version(">= 1.3.5", "< 1.4.0") Vagrant.require_version("~> 1.3.5")



204
205
206
207
208
209
210
211
212
213
214
215
216
217
# File 'lib/vagrant.rb', line 204

def self.require_version(*requirements)
  logger = Log4r::Logger.new("vagrant::root")
  logger.info("Version requirements from Vagrantfile: #{requirements.inspect}")

  req = Gem::Requirement.new(*requirements)
  if req.satisfied_by?(Gem::Version.new(VERSION))
    logger.info("  - Version requirements satisfied!")
    return
  end

  raise Errors::VagrantVersionBad,
    requirements: requirements.join(", "),
    version: VERSION
end

+ (String) server_url

Returns the URL prefix to the server.

Returns:

  • (String)


63
64
65
66
67
# File 'lib/vagrant/shared_helpers.rb', line 63

def self.server_url
  result = ENV["VAGRANT_SERVER_URL"]
  result = nil if result == ""
  result || DEFAULT_SERVER_URL
end

+ (Pathname) source_root

The source root is the path to the root directory of the Vagrant source.

Returns:

  • (Pathname)


72
73
74
# File 'lib/vagrant/shared_helpers.rb', line 72

def self.source_root
  @source_root ||= Pathname.new(File.expand_path('../../../', __FILE__))
end

+ (Pathname) user_data_path

This returns the path to the ~/.vagrant.d folder where Vagrant's per-user state is stored.

Returns:

  • (Pathname)


80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
# File 'lib/vagrant/shared_helpers.rb', line 80

def self.user_data_path
  # Use user spcified env var if available
  path = ENV["VAGRANT_HOME"]

  # On Windows, we default ot the USERPROFILE directory if it
  # is available. This is more compatible with Cygwin and sharing
  # the home directory across shells.
  if !path && ENV["USERPROFILE"]
    path = "#{ENV["USERPROFILE"]}/.vagrant.d"
  end

  # Fallback to the default
  path ||= "~/.vagrant.d"

  Pathname.new(path).expand_path
end

+ (Boolean) very_quiet?

Whether or not super quiet mode is enabled. This is ill-advised.

Returns:

  • (Boolean)


56
57
58
# File 'lib/vagrant/shared_helpers.rb', line 56

def self.very_quiet?
  !!ENV["VAGRANT_I_KNOW_WHAT_IM_DOING_PLEASE_BE_QUIET"]
end