open-vault/website/content/docs/internals/plugins.mdx

---
layout: docs
page_title: Plugin System
description: Learn about Vault's plugin system.
---

# Plugin System

All Vault auth and secret backends are considered plugins. This simple concept
allows both built-in and external plugins to be treated like Legos. Any plugin
can exist at multiple different locations. Different versions of a plugin may
be at each one, with each version differing from Vault's version.

## Built-In Plugins

Built-in plugins are shipped with Vault, often for commonly used implementations,
and require no additional operator intervention to run. Built-in plugins are
just like any other backend code inside Vault.

To use a different or edited version of a built-in plugin, you would first edit
the plugin's code or navigate to the Vault version holding the version of the
plugin you desire. Then, you'd `$ cd` into the `cmd/:plugin-name` directory
contained alongside that plugin's code. For instance, for AppRole, you would:
`$ cd vault/builtin/credential/approle/cmd/approle`. Once in that directory,
you would run `$ go build` to obtain a new binary for the AppRole plugin. Then
you would add it to the plugin catalog as per normal, and enable it.

# 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.

It is possible to enable a custom plugin with a name that's identical to a
built-in plugin. In such a situation, Vault will always choose the custom plugin
when enabling it.

## Plugin Lifecycle

Vault plugins are long-running processes that remain running once they are
spawned by Vault, the parent process. Plugin processes can be started by Vault's
active node and performance standby nodes. Additionally, there are cases where
plugin processes may be terminated by Vault. These cases include but are not
limited to:

- Vault active node step-down
- Vault barrier seal
- Vault graceful shutdown
- Disabling a Secrets Engine or Auth method that uses external plugins
- Database configured connection deletion
- Database configured connection update
- Database configured connection reset request
- Database root credentials rotation
- WAL Rollback from a previously failed root credentials rotation operation

The lifecycle of plugin processes are managed automatically by Vault.
Termination of these processes are typical in certain scenarios, such as the
ones listed above. Vault will start plugin processes when needed, typically by
lazily loading the plugin when a request that requires the plugin is received by
Vault. A plugin process may be started or terminated through other internal
processes within Vault as well. Since Vault manages and tracks the lifecycle of
its plugins, these processes should not be terminated by anything other than
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](/docs/concepts/response-wrapping) 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 to
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](/docs/configuration).
This setting specifies a directory in which all plugin binaries must live;
_this value cannot be a symbolic link_. 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).

An example of plugin registration in current versions of Vault:

```shell-session
$ vault plugin register -sha256=<SHA256 Hex value of the plugin binary> \
    secret \                  # type
    myplugin-database-plugin

Success! Registered plugin: myplugin-database-plugin
```

Vault versions prior to v0.10.4 lacked the `vault plugin` operator and the
registration step for them is:

```shell-session
$ vault write sys/plugins/catalog/database/myplugin-database-plugin \
     sha256=<SHA256 Hex value of the plugin binary> \
     command="myplugin"

Success! Data written to: sys/plugins/catalog/database/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](/docs/configuration#disable_mlock).

~> Note: If Vault is configured with `mlock` enabled, then the Vault executable and each
plugin executable in your [plugins directory](/docs/internals/plugins#plugin-directory) must be
given the ability to use the `mlock` syscall.

### Plugin Upgrades

Plugins may be updated by registering and reloading them. More details on the
upgrade procedure can be found in [Upgrading Vault Plugins](/docs/upgrading/plugins).

### Troubleshooting

#### Unrecognized remote plugin message

If the following error is encountered when enabling a plugin secret engine or
auth method:

```sh
Unrecognized remote plugin message:

This usually means that the plugin is either invalid or simply
needs to be recompiled to support the latest protocol.
```

Verify whether the Vault process has `mlock` enabled, and if so run the
following command against the plugin binary:

```sh
sudo setcap cap_ipc_lock=+ep <plugin-binary>
```

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

	myPlugin "your/plugin/import/path"
	"github.com/hashicorp/vault/api"
	"github.com/hashicorp/vault/sdk/plugin"
)

func main() {
	apiClientMeta := &api.PluginAPIClientMeta{}
	flags := apiClientMeta.FlagSet()
	flags.Parse(os.Args[1:])

	tlsConfig := apiClientMeta.GetTLSConfig()
	tlsProviderFunc := api.VaultPluginTLSProvider(tlsConfig)

	err := plugin.Serve(&plugin.ServeOpts{
		BackendFactoryFunc: myPlugin.Factory,
		TLSProviderFunc:    tlsProviderFunc,
	})
	if err != nil {
		logger := hclog.New(&hclog.LoggerOptions{})

		logger.Error("plugin shutting down", "error", err)
		os.Exit(1)
	}
}
```

And that's basically it! You would just need to change `myPlugin` to your actual
plugin. For more information on how to register and enable your plugin, check out the [Building Plugin Backends](https://learn.hashicorp.com/vault/developer/plugin-backends) tutorial.

[api_addr]: /docs/configuration#api_addr