Plugin Development: Guest Capabilities

This page documents how to add new capabilities for guests to Vagrant, allowing Vagrant to perform new actions on specific guest operating systems. Prior to reading this, you should be familiar with the plugin development basics.

Warning: Advanced Topic! Developing plugins is an advanced topic that only experienced Vagrant users who are reasonably comfortable with Ruby should approach.

Guest capabilities augment guests by attaching specific "capabilities" to the guest, which are actions that can be performed in the context of that guest operating system.

The power of capabilities is that plugins can add new capabilities to existing guest operating systems without modifying the core of Vagrant. In earlier versions of Vagrant, all the guest logic was contained in the core of Vagrant and was not easily augmented.

Definition Component

Within the context of a plugin definition, guest capabilities can be defined like so:

guest_capability "ubuntu", "my_custom_capability" do
  require_relative "cap/my_custom_capability"
  Cap::MyCustomCapability
end

Guest capabilities are defined by calling the guest_capability method, which takes two parameters: the guest to add the capability to, and the name of the capability itself. Then, the block argument returns a class that implements a method named the same as the capability. This is covered in more detail in the next section.

Implementation

Implementations should be classes or modules that have a method with the same name as the capability. The method must be immediately accessible on the class returned from the guest_capability component, meaning that if it is an instance method, an instance should be returned.

In general, class methods are used for capabilities. For example, here is the implementation for the capability above:

module Cap
  class MyCustomCapability
    def self.my_custom_capability(machine)
      # implementation
    end
  end
end

All capabilities get the Vagrant machine object as the first argument. Additional arguments are determined by the specific capability, so view the documentation or usage of the capability you are trying to implement for more information.

Some capabilities must also return values back to the caller, so be aware of that when implementing a capability.

Capabilities always have access to communication channels such as SSH on the machine, and the machine can generally be assumed to be booted.

Calling Capabilities

Since you have access to the machine in every capability, capabilities can also call other capabilities. This is useful for using the inheritance mechanism of capabilities to potentially ask helpers for more information. For example, the "redhat" guest has a "network_scripts_dir" capability that simply returns the directory where networking scripts go.

Capabilities on child guests of RedHat such as CentOS or Fedora use this capability to determine where networking scripts go, while sometimes overriding it themselves.

Capabilities can be called like so:

machine.guest.capability(:capability_name)

Any additional arguments given to the method will be passed on to the capability, and the capability will return the value that the actual capability returned.