a3dfde5cec
* conversion stage 1 * correct image paths * add sidebar title to frontmatter * docs/concepts and docs/internals * configuration docs and multi-level nav corrections * commands docs, index file corrections, small item nav correction * secrets converted * auth * add enterprise and agent docs * add extra dividers * secret section, wip * correct sidebar nav title in front matter for apu section, start working on api items * auth and backend, a couple directory structure fixes * remove old docs * intro side nav converted * reset sidebar styles, add hashi-global-styles * basic styling for nav sidebar * folder collapse functionality * patch up border length on last list item * wip restructure for content component * taking middleman hacking to the extreme, but its working * small css fix * add new mega nav * fix a small mistake from the rebase * fix a content resolution issue with middleman * title a couple missing docs pages * update deps, remove temporary markup * community page * footer to layout, community page css adjustments * wip downloads page * deps updated, downloads page ready * fix community page * homepage progress * add components, adjust spacing * docs and api landing pages * a bunch of fixes, add docs and api landing pages * update deps, add deploy scripts * add readme note * update deploy command * overview page, index title * Update doc fields Note this still requires the link fields to be populated -- this is solely related to copy on the description fields * Update api_basic_categories.yml Updated API category descriptions. Like the document descriptions you'll still need to update the link headers to the proper target pages. * Add bottom hero, adjust CSS, responsive friendly * Add mega nav title * homepage adjustments, asset boosts * small fixes * docs page styling fixes * meganav title * some category link corrections * Update API categories page updated to reflect the second level headings for api categories * Update docs_detailed_categories.yml Updated to represent the existing docs structure * Update docs_detailed_categories.yml * docs page data fix, extra operator page remove * api data fix * fix makefile * update deps, add product subnav to docs and api landing pages * Rearrange non-hands-on guides to _docs_ Since there is no place for these on learn.hashicorp, we'll put them under _docs_. * WIP Redirects for guides to docs * content and component updates * font weight hotfix, redirects * fix guides and intro sidenavs * fix some redirects * small style tweaks * Redirects to learn and internally to docs * Remove redirect to `/vault` * Remove `.html` from destination on redirects * fix incorrect index redirect * final touchups * address feedback from michell for makefile and product downloads
136 lines
6 KiB
Markdown
136 lines
6 KiB
Markdown
---
|
|
layout: "docs"
|
|
page_title: "Plugin System"
|
|
sidebar_title: "Plugins"
|
|
sidebar_current: "docs-internals-plugins"
|
|
description: |-
|
|
Learn about Vault's plugin system.
|
|
---
|
|
|
|
# Plugin System
|
|
Certain Vault backends utilize plugins to extend their functionality outside of
|
|
what is available in the core Vault code. Often times these backends will
|
|
provide both builtin plugins and a mechanism for executing external plugins.
|
|
Builtin plugins are shipped with Vault, often for commonly used implementations,
|
|
and require no additional operator intervention to run. Builtin plugins are
|
|
just like any other backend code inside Vault. External plugins, on the other
|
|
hand, are not shipped with the Vault binary and must be registered to Vault by
|
|
a privileged Vault user. This section of the documentation will describe the
|
|
architecture and security of external plugins.
|
|
|
|
# Plugin Architecture
|
|
Vault's plugins are completely separate, standalone applications that Vault
|
|
executes and communicates with over RPC. This means the plugin process does not
|
|
share the same memory space as Vault and therefore can only access the
|
|
interfaces and arguments given to it. This also means a crash in a plugin can not
|
|
crash the entirety of Vault.
|
|
|
|
## Plugin Communication
|
|
Vault creates a mutually authenticated TLS connection for communication with the
|
|
plugin's RPC server. While invoking the plugin process, Vault passes a [wrapping
|
|
token](https://www.vaultproject.io/docs/concepts/response-wrapping.html) to the
|
|
plugin process' environment. This token is single use and has a short TTL. Once
|
|
unwrapped, it provides the plugin with a uniquely generated TLS certificate and
|
|
private key for it to use to talk to the original Vault process.
|
|
|
|
The [`api_addr`][api_addr] must be set in order for the plugin process establish
|
|
communication with the Vault server during mount time. If the storage backend
|
|
has HA enabled and supports automatic host address detection (e.g. Consul),
|
|
Vault will automatically attempt to determine the `api_addr` as well.
|
|
|
|
~> Note: Reading the original connection's TLS connection state is not supported
|
|
in plugins.
|
|
|
|
## Plugin Registration
|
|
An important consideration of Vault's plugin system is to ensure the plugin
|
|
invoked by Vault is authentic and maintains integrity. There are two components
|
|
that a Vault operator needs to configure before external plugins can be run, the
|
|
plugin directory and the plugin catalog entry.
|
|
|
|
### Plugin Directory
|
|
The plugin directory is a configuration option of Vault, and can be specified in
|
|
the [configuration file](https://www.vaultproject.io/docs/configuration/index.html).
|
|
This setting specifies a directory that all plugin binaries must live. A plugin
|
|
can not be added to Vault unless it exists in the plugin directory. There is no
|
|
default for this configuration option, and if it is not set plugins can not be
|
|
added to Vault.
|
|
|
|
~> Warning: A Vault operator should take care to lock down the permissions on
|
|
this directory to ensure a plugin can not be modified by an unauthorized user
|
|
between the time of the SHA check and the time of plugin execution.
|
|
|
|
### Plugin Catalog
|
|
The plugin catalog is Vault's list of approved plugins. The catalog is stored in
|
|
Vault's barrier and can only be updated by a Vault user with sudo permissions.
|
|
Upon adding a new plugin, the plugin name, SHA256 sum of the executable, and the
|
|
command that should be used to run the plugin must be provided. The catalog will
|
|
make sure the executable referenced in the command exists in the plugin
|
|
directory. When added to the catalog the plugin is not automatically executed,
|
|
it instead becomes visible to backends and can be executed by them. For more
|
|
information on the plugin catalog please see the [Plugin Catalog API
|
|
docs](/api/system/plugins-catalog.html).
|
|
|
|
An example plugin submission looks like:
|
|
|
|
```
|
|
$ vault write sys/plugins/catalog/myplugin-database-plugin \
|
|
sha256=<expected SHA256 Hex value of the plugin binary> \
|
|
command="myplugin"
|
|
Success! Data written to: sys/plugins/catalog/myplugin-database-plugin
|
|
```
|
|
|
|
### Plugin Execution
|
|
When a backend wants to run a plugin, it first looks up the plugin, by name, in
|
|
the catalog. It then checks the executable's SHA256 sum against the one
|
|
configured in the plugin catalog. Finally Vault runs the command configured in
|
|
the catalog, sending along the JWT formatted response wrapping token and mlock
|
|
settings (like Vault, plugins support [the use of mlock when available](https://www.vaultproject.io/docs/configuration/index.html#disable_mlock)).
|
|
|
|
# Plugin Development
|
|
|
|
~> Advanced topic! Plugin development is a highly advanced topic in Vault, and
|
|
is not required knowledge for day-to-day usage. If you don't plan on writing any
|
|
plugins, we recommend not reading this section of the documentation.
|
|
|
|
Because Vault communicates to plugins over a RPC interface, you can build and
|
|
distribute a plugin for Vault without having to rebuild Vault itself. This makes
|
|
it easy for you to build a Vault plugin for your organization's internal use,
|
|
for a proprietary API that you don't want to open source, or to prototype
|
|
something before contributing it back to the main project.
|
|
|
|
In theory, because the plugin interface is HTTP, you could even develop a plugin
|
|
using a completely different programming language! (Disclaimer, you would also
|
|
have to re-implement the plugin API which is not a trivial amount of work.)
|
|
|
|
Developing a plugin is simple. The only knowledge necessary to write
|
|
a plugin is basic command-line skills and basic knowledge of the
|
|
[Go programming language](http://golang.org).
|
|
|
|
Your plugin implementation needs to satisfy the interface for the plugin
|
|
type you want to build. You can find these definitions in the docs for the
|
|
backend running the plugin.
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"os"
|
|
|
|
"github.com/hashicorp/vault/helper/pluginutil"
|
|
"github.com/hashicorp/vault/plugins"
|
|
)
|
|
|
|
func main() {
|
|
apiClientMeta := &pluginutil.APIClientMeta{}
|
|
flags := apiClientMeta.FlagSet()
|
|
flags.Parse(os.Args)
|
|
|
|
plugins.Serve(New().(MyPlugin), apiClientMeta.GetTLSConfig())
|
|
}
|
|
```
|
|
|
|
And that's basically it! You would just need to change MyPlugin to your actual
|
|
plugin.
|
|
|
|
[api_addr]: /docs/configuration/index.html#api_addr
|