105 lines
3.8 KiB
Markdown
105 lines
3.8 KiB
Markdown
---
|
|
layout: "docs"
|
|
page_title: "Guest Capabilities - Plugin Development"
|
|
sidebar_current: "plugins-guestcapabilities"
|
|
description: |-
|
|
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.
|
|
---
|
|
|
|
# Plugin Development: Guest Capabilities
|
|
|
|
This page documents how to add new capabilities for [guests](/docs/plugins/guests.html)
|
|
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](/docs/plugins/development-basics.html).
|
|
|
|
<div class="alert alert-warning">
|
|
<strong>Warning: Advanced Topic!</strong> Developing plugins is an
|
|
advanced topic that only experienced Vagrant users who are reasonably
|
|
comfortable with Ruby should approach.
|
|
</div>
|
|
|
|
Guest capabilities augment [guests](/docs/plugins/guests.html) 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:
|
|
|
|
```ruby
|
|
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:
|
|
|
|
```ruby
|
|
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:
|
|
|
|
```ruby
|
|
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.
|