vault/website/content/docs/plugins/plugin-management.mdx

---
layout: docs
page_title: Plugin management
description: >-
   Learn how to manage external plugins that are implemented using Vault's plugin system.
---


# Plugin management

External plugins are the components in Vault that can be implemented separately
from Vault's built-in plugins. These plugins can be either authentication or
secrets engines.

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.

Detailed information regarding the plugin system can be found in the
[internals documentation](/vault/docs/plugins).

## Registering external plugins

Before an external plugin can be mounted, it needs to be
[registered](/vault/docs/plugins/plugin-architecture#plugin-registration) in the
plugin catalog to ensure the plugin invoked by Vault is authentic and maintains
integrity:

### Community plugins

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

Success! Registered plugin: passthrough-plugin
```

### Enterprise plugins

@include 'alerts/enterprise-and-hcp.mdx'

#### Compatible Vault Enterprise versions
- 1.16.16+
- 1.17.12+
- 1.18.5+
- 1.19.0+

Before registering an enterprise plugin, ensure that the plugin artifact
compatible with the system that runs Vault Enterprise is downloaded from
[HashiCorp releases page](https://releases.hashicorp.com/) and placed
in the plugin directory.

~> Note: Enterprise plugins artifacts should not be unzipped or modified
in any way. Vault Enterprise will verify the plugin's integrity
and compatibility and unzip during the registration process.

```shell-session
$ vault plugin register 
    -version=<version of the plugin> # version must match the plugin version on the releases page
    secret \                         # type
    vault-plugin-secrets-keymgmt     # name must match the plugin name on the releases page

Success! Registered plugin: vault-plugin-secrets-keymgmt
```

See [plugin register](/vault/docs/commands/plugin/register) for more details on 
how to register Enterprise plugins.

## Enabling/Disabling external plugins

After the plugin is registered, it can be mounted by specifying the registered
plugin name:

```shell-session
$ vault secrets enable -path=my-secrets passthrough-plugin
Success! Enabled the passthrough-plugin secrets engine at: my-secrets/
```

Listing secrets engines will display secrets engines that are mounted as
plugins:

```shell-session
$ vault secrets list
Path         Type       Accessor            Plugin              Default TTL  Max TTL  Force No Cache  Replication Behavior  Description
my-secrets/  plugin     plugin_deb84140     passthrough-plugin  system       system   false           replicated
```

Disabling an external plugins is identical to disabling a built-in plugin:

```shell-session
$ vault secrets disable my-secrets
```

## Upgrading plugins

Upgrade instructions can be found in the [Upgrading Plugins - Guides][upgrading_plugins]
page.

[api_addr]: /vault/docs/configuration#api_addr
[upgrading_plugins]: /vault/docs/upgrading/plugins

## Plugin environment variables

An advantage for external plugins over builtin plugins is they can specify
additional environment variables because they are run in their own process.

-> Vault 1.16.0 changed the precedence given to plugin-specific environment
variables so they take priority over Vault's environment. See full details in
the [upgrade notes](/vault/docs/upgrading/upgrade-to-1.16.x).

Use the `-env` flag once per environment variable that a plugin should be
started with:

```shell-session
$ vault plugin register -sha256=<SHA256 Hex value of the plugin binary> \
    -env REGION=eu \
    -env TOKEN_FILE=/var/run/token \
    secret \                  # type
    passthrough-plugin

Success! Registered plugin: passthrough-plugin
```

### Plugin-specific HTTP proxy settings

Many tools and libraries automatically consume `HTTP_PROXY`, `HTTPS_PROXY`, and
`NO_PROXY` environment variables to configure HTTP proxy settings, including the
Go standard library's default HTTP client. You can use these environment
variables to configure different network proxies for different plugins:

-> You must be using an external plugin to take advantage of custom environment
variables. If you are using a builtin plugin, you can still download and register
an external version of it in order to use this workflow. Check the
[HashiCorp releases page](https://releases.hashicorp.com/) for the latest
prebuilt plugin binaries.

#### Community plugins
```shell-session
$ vault plugin register -sha256=<SHA256 Hex value of the plugin binary> \
    -env HTTP_PROXY=eu.example.com \
    auth \
    jwt-eu

Success! Registered plugin: jwt-eu

$ vault plugin register -sha256=<SHA256 Hex value of the plugin binary> \
    -env HTTP_PROXY=us.example.com \
    auth \
    jwt-us

Success! Registered plugin: jwt-us
```

#### Enterprise plugins
```shell-session
$ vault plugin register -version=<version of the plugin> \
    -env HTTP_PROXY=example.com \
    secret \
    vault-plugin-secrets-keymgmt

Success! Registered plugin: vault-plugin-secrets-keymgmt
```

You can then enable each plugin on its own path, and configure clients that
should be associated with one or the other appropriately:

```shell-session
$ vault auth enable jwt-eu
Success! Enabled the jwt-eu auth method at: auth/jwt-eu/

$ vault auth enable jwt-us
Success! Enabled the jwt-us auth method at: auth/jwt-us/

$ vault secrets enable vault-plugin-secrets-keymgmt
Success! Enabled the vault-plugin-secrets-keymgmt secrets engine at: vault-plugin-secrets-keymgmt/
```