---
layout: docs
page_title: Plugin architecture
description: >-
    Learn how plugin processes run and interact with Vault.
---

> [!IMPORTANT]  
> **Documentation Update:** Product documentation, which were located in this repository under `/website`, are now located in [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs), colocated with all other product documentation. Contributions to this content should be done in the `web-unified-docs` repo, and not this one. Changes made to `/website` content in this repo will not be reflected on the developer.hashicorp.com website.

# Plugin architecture

Plugins are separate, standalone applications with have predefined interfaces
and parameters. Vault executes and communicates with plugins over RPC. Plugins
do not share memory space with Vault and a crash in the plugin cannot crash the
entirety of Vault.


## Plugin registration

An important consideration of the plugin system is ensuring any plugin invoked
by Vault is authentic and maintains integrity. As a result, Vault only allows
manual plugin registration from an explicitly configured **plugin directory**
and only enables plugins with a valid **catalog** entry.

The plugin directory must be accessible from the Vault server and cannot be a
symbolic link. The default Vault configuration does not include a plugin
directory and you cannot register plugins manually until you configure a plugin
directory.

The plugin catalog lives at the Vault barrier and tracks currently registered
plugins. At registration time, Vault verifies the plugin artifact exists in the
plugin directory and matches the provided SHA256 checksum before updating the
catalog.

Registering a plugin makes the plugin visible and executable by Vault backends,
but the plugin process does not run until you enable it on a specific mount path.

@include 'tips/get-plugins.mdx'


## Plugin process execution

Before starting a plugin process, Vault looks up the plugin by name in the
plugin catalog and checks the SHA256 of the plugin artifact against the registered
SHA256 sum. If the sums match, Vault starts the plugin using the command
registered in the catalog along with a JWT formatted response wrapping token and
any relevant [mlock](/vault/docs/configuration#disable_mlock) settings.

Vault spawns built-in plugins within the Vault process and external plugins as
separate processes, with Vault as the parent process.

Active Vault nodes and performance standby nodes can both spawn external plugin
processes. Plugin processes continue to run after spawning until Vault
explicitly terminates them. Common termination events are:

- Vault active node step-down
- Vault barrier seal
- Vault graceful shutdown
- Disabling a secrets engine or authN 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

Vault manages the plugin process lifecycle automatically. The process starts
when you enable a plugin, but Vault starts and terminates the plugin processes
as needed through other internal processes. Since Vault manages and tracks the
lifecycle of its plugins, we do not recommend terminating plugins manually.
If Vault terminates a plugin process out-of-band, Vault lazily reloads the
process when it receives a client request that requires the plugin.

### Multiplexing

Vault allows plugin multiplexing to avoid spawning multiple processes for mounts
of the same type. When Vault runs plugins that implement multiplexing, it uses a
single plugin process for all mounts of that type across all Vault namespaces.
Multiplexing a plugin does not affect the current behavior of existing
plugins.

More resources on implementing plugin multiplexing:

- [Database secrets engines](/vault/docs/secrets/databases/custom#serving-a-plugin-with-multiplexing)
- [Secrets engines and auth methods](/vault/docs/plugins/plugin-development)


## Plugin communication

Vault communicates securely with plugins through a mutually authenticated
TLS connection to the RPC server on the plugin side. HashiCorp-managed plugins
use the AutoMTLS feature of [go-plugin](https://www.github.com/hashicorp/go-plugin)
to automatically negotiate mutual TLS for transport authentication.

Built-in plugins included with the Vault binary at compile time already
know the correct API address to establish a TLS connection, but you must set the
[`api_addr`](/vault/docs/configuration#api_addr) parameter in your Vault
configuration so manually registered plugins can establish communication with
the Vault server at mount time. If the storage backend has HA enabled and
supports automatic host address detection (e.g. Consul), Vault tries to
determine the `api_addr` automatically.


## Performance scaling

Plugins running in Vault Enterprise can leverage
[performance standbys](/vault/docs/enterprise/performance-standby) without
explicit action by the plugin author. By default, Vault Enterprise tries to
handle all requests, including requests to plugins, on performance standbys.

If the plugin request tries to write to storage, the request receives a
read-only error, and Vault transparently re-routes the full, original request to
the active node. As a result, plugins can scale horizontally on Vault Enterprise
without explicit code changes to the plugin.
