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/action.rb,
lib/vagrant/plugin.rb,
lib/vagrant/config.rb,
lib/vagrant/util/io.rb,
lib/vagrant/bundler.rb,
lib/vagrant/machine.rb,
lib/vagrant/version.rb,
lib/vagrant/util/ssh.rb,
lib/vagrant/registry.rb,
lib/vagrant/util/env.rb,
lib/vagrant/util/busy.rb,
lib/vagrant/plugin/v1.rb,
lib/vagrant/config/v2.rb,
lib/vagrant/config/v1.rb,
lib/vagrant/plugin/v2.rb,
lib/vagrant/util/which.rb,
lib/vagrant/environment.rb,
lib/vagrant/action/hook.rb,
lib/vagrant/vagrantfile.rb,
lib/vagrant/util/counter.rb,
lib/vagrant/batch_action.rb,
lib/vagrant/box_metadata.rb,
lib/vagrant/util/keypair.rb,
lib/vagrant/action/runner.rb,
lib/vagrant/action/warden.rb,
lib/vagrant/util/platform.rb,
lib/vagrant/config/loader.rb,
lib/vagrant/machine_state.rb,
lib/vagrant/machine_index.rb,
lib/vagrant/box_collection.rb,
lib/vagrant/plugin/v2/push.rb,
lib/vagrant/util/retryable.rb,
lib/vagrant/plugin/manager.rb,
lib/vagrant/util/file_mode.rb,
lib/vagrant/shared_helpers.rb,
lib/vagrant/plugin/v1/host.rb,
lib/vagrant/util/safe_puts.rb,
lib/vagrant/config/v1/root.rb,
lib/vagrant/action/builder.rb,
lib/vagrant/util/safe_exec.rb,
lib/vagrant/config/v2/root.rb,
lib/vagrant/config/v2/util.rb,
lib/vagrant/plugin/v2/host.rb,
lib/vagrant/util/deep_merge.rb,
lib/vagrant/plugin/v1/guest.rb,
lib/vagrant/plugin/v2/guest.rb,
lib/vagrant/util/network_ip.rb,
lib/vagrant/util/downloader.rb,
lib/vagrant/capability_host.rb,
lib/vagrant/util/safe_chdir.rb,
lib/vagrant/util/powershell.rb,
lib/vagrant/util/subprocess.rb,
lib/vagrant/plugin/v2/plugin.rb,
lib/vagrant/plugin/v1/config.rb,
lib/vagrant/plugin/v2/errors.rb,
lib/vagrant/config/v2/loader.rb,
lib/vagrant/util/shell_quote.rb,
lib/vagrant/plugin/v2/config.rb,
lib/vagrant/plugin/v1/plugin.rb,
lib/vagrant/config/v1/loader.rb,
lib/vagrant/plugin/v1/errors.rb,
lib/vagrant/plugin/v1/command.rb,
lib/vagrant/plugin/v1/manager.rb,
lib/vagrant/plugin/v2/manager.rb,
lib/vagrant/plugin/state_file.rb,
lib/vagrant/util/is_port_open.rb,
lib/vagrant/plugin/v2/command.rb,
lib/vagrant/plugin/v1/provider.rb,
lib/vagrant/plugin/v2/provider.rb,
lib/vagrant/config/version_base.rb,
lib/vagrant/action/builtin/lock.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/action/general/package.rb,
lib/vagrant/action/builtin/box_add.rb,
lib/vagrant/config/v2/dummy_config.rb,
lib/vagrant/action/builtin/ssh_run.rb,
lib/vagrant/plugin/v2/communicator.rb,
lib/vagrant/config/v1/dummy_config.rb,
lib/vagrant/action/builtin/confirm.rb,
lib/vagrant/action/builtin/env_set.rb,
lib/vagrant/util/template_renderer.rb,
lib/vagrant/plugin/v1/communicator.rb,
lib/vagrant/action/builtin/message.rb,
lib/vagrant/action/builtin/is_state.rb,
lib/vagrant/plugin/v2/synced_folder.rb,
lib/vagrant/action/builtin/ssh_exec.rb,
lib/vagrant/util/stacked_proc_runner.rb,
lib/vagrant/util/string_block_editor.rb,
lib/vagrant/util/line_ending_helpers.rb,
lib/vagrant/action/builtin/provision.rb,
lib/vagrant/action/builtin/handle_box.rb,
lib/vagrant/action/builtin/box_remove.rb,
lib/vagrant/action/builtin/box_update.rb,
lib/vagrant/util/scoped_hash_override.rb,
lib/vagrant/action/builtin/set_hostname.rb,
lib/vagrant/action/builtin/graceful_halt.rb,
lib/vagrant/action/builtin/handle_box_url.rb,
lib/vagrant/action/builtin/synced_folders.rb,
lib/vagrant/util/ansi_escape_code_remover.rb,
lib/vagrant/action/builtin/destroy_confirm.rb,
lib/vagrant/action/builtin/config_validate.rb,
lib/vagrant/action/builtin/mixin_provisioners.rb,
lib/vagrant/action/builtin/box_check_outdated.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/wait_for_communicator.rb,
lib/vagrant/action/builtin/synced_folder_cleanup.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", :push])         { Plugin::V2::Push }
  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 Atlas in use. API calls will be made to this for various functions of Vagrant that may require remote access.

Returns:

  • (String)
"https://atlas.hashicorp.com"
@@global_lock =
Mutex.new

Class Method Summary collapse

Class Method Details

.configure(version, &block) ⇒ Object

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



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

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

.global_lockObject

This holds a global lock for the duration of the block. This should be invoked around anything that is modifying process state (such as environmental variables).



18
19
20
21
22
# File 'lib/vagrant/shared_helpers.rb', line 18

def self.global_lock
  @@global_lock.synchronize do
    return yield
  end
end

.has_plugin?(name, version = nil) ⇒ Boolean

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)


145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
# File 'lib/vagrant.rb', line 145

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

  # Make the requirement object
  version = Gem::Requirement.new([version]) if version

  # Now check the plugin gem names
  require "vagrant/plugin/manager"
  Plugin::Manager.instance.installed_specs.any? do |s|
    match = s.name == name
    next match if !version
    next version.satisfied_by?(s.version)
  end
end

.in_installer?Boolean

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

Returns:

  • (Boolean)


28
29
30
# File 'lib/vagrant/shared_helpers.rb', line 28

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

.installer_embedded_dirString

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

Returns:

  • (String)


36
37
38
39
# File 'lib/vagrant/shared_helpers.rb', line 36

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

.plugin(version, component = nil) ⇒ Class

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)


180
181
182
183
184
185
186
187
188
189
190
191
192
193
# File 'lib/vagrant.rb', line 180

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

.plugins_enabled?Boolean

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

Returns:

  • (Boolean)


44
45
46
# File 'lib/vagrant/shared_helpers.rb', line 44

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

.require_plugin(name) ⇒ Object

Deprecated.


196
197
198
199
200
# File 'lib/vagrant.rb', line 196

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

.require_version(*requirements) ⇒ Object

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")



214
215
216
217
218
219
220
221
222
223
224
225
226
227
# File 'lib/vagrant.rb', line 214

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

.server_url(config_server_url = nil) ⇒ String

Returns the URL prefix to the server.

Returns:

  • (String)


58
59
60
61
62
# File 'lib/vagrant/shared_helpers.rb', line 58

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

.source_rootPathname

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

Returns:

  • (Pathname)


67
68
69
# File 'lib/vagrant/shared_helpers.rb', line 67

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

.user_data_pathPathname

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

Returns:

  • (Pathname)


75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
# File 'lib/vagrant/shared_helpers.rb', line 75

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

  # On Windows, we default to 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

.very_quiet?Boolean

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

Returns:

  • (Boolean)


51
52
53
# File 'lib/vagrant/shared_helpers.rb', line 51

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