ec620a7765
* implement mdx remote * fix an unfenced code block * fix partials path Co-authored-by: Jim Kalafut <jkalafut@hashicorp.com>
125 lines
3.7 KiB
Plaintext
125 lines
3.7 KiB
Plaintext
---
|
|
layout: guides
|
|
page_title: Plugin Backends - Guides
|
|
sidebar_title: Building Plugin Backends
|
|
description: 'Learn how to build, register, and mount a custom plugin backend.'
|
|
---
|
|
|
|
# Introduction
|
|
|
|
Plugin backends utilize the [plugin system][plugin-system] to enable third-party
|
|
secrets engines and auth methods.
|
|
|
|
It is worth noting that even though [database secrets engines][database-backend]
|
|
operate under the same underlying plugin mechanism, they are slightly different
|
|
in design than plugin backends demonstrated in this guide. The database secrets
|
|
engine manages multiple plugins under the same backend mount point, whereas
|
|
plugin backends are kv backends that function as either secret or auth methods.
|
|
|
|
This guide provides steps to build, register, and mount non-database external
|
|
plugin backends.
|
|
|
|
## Setup Vault
|
|
|
|
Set `plugin_directory` to the desired path in the Vault configuration file.
|
|
The path should exist and have proper lockdown on access permissions.
|
|
|
|
```hcl
|
|
# /etc/vault/config.d/plugins.hcl
|
|
plugin_directory = "/etc/vault/vault_plugins"
|
|
```
|
|
|
|
If the Vault server is already running, you will need to tell it to reload its
|
|
configuration by sending SIGHUP. If you stop and start the Vault server, you
|
|
will need to unseal it again.
|
|
|
|
## Compile Plugin
|
|
|
|
Build the custom binary, and move it inside the `plugin_directory` path
|
|
configured above. This guide uses `mock-plugin` that comes from Vault's
|
|
[`logical/plugin/mock`](https://github.com/hashicorp/vault/tree/master/logical/plugin/mock/mock-plugin) package.
|
|
|
|
Download the source (you would probably use your own plugin):
|
|
|
|
```shell-session
|
|
$ go get -f -u -d github.com/hashicorp/vault
|
|
# ...
|
|
$ cd $GOPATH/src/github.com/hashicorp/vault/sdk/plugin/mock/mock-plugin
|
|
```
|
|
|
|
Compile the plugin:
|
|
|
|
```shell-session
|
|
$ go build -o my-mock-plugin
|
|
```
|
|
|
|
Put the plugin in the directory:
|
|
|
|
```shell-session
|
|
$ mv my-mock-plugin /etc/vault/vault_plugins
|
|
```
|
|
|
|
Alternatively, if you wanted a custom version of a plugin built into Vault, such as AppRole:
|
|
|
|
```shell-session
|
|
$ cd $GOPATH/src/github.com/hashicorp/vault/builtin/credential/approle/cmd/approle
|
|
$ go build
|
|
$ mv approle /etc/vault/vault_plugins
|
|
```
|
|
|
|
## Register in Plugin Catalog
|
|
|
|
Calculate the SHA256 sum of the compiled plugin binary, and use that to register
|
|
the plugin into Vault's plugin catalog:
|
|
|
|
```shell-session
|
|
$ shasum -a 256 /etc/vault/vault_plugins/my-mock-plugin
|
|
2c071aafa1b30897e60b79643e77592cb9d1e8f803025d44a7f9bbfa4779d615 /etc/vault/vault_plugins/my-mock-plugin
|
|
|
|
$ vault write sys/plugins/catalog/secret/my-mock-plugin \
|
|
sha256=2c071aafa1b30897e60b79643e77592cb9d1e8f803025d44a7f9bbfa4779d615 \
|
|
command=my-mock-plugin
|
|
Success! Data written to: sys/plugins/catalog/secret/my-mock-plugin
|
|
```
|
|
|
|
## Enable Plugin
|
|
|
|
Enabling the plugin varies depending on if it's a secrets engine or auth method:
|
|
|
|
```shell-session
|
|
$ vault secrets enable -path=my-secrets-plugin my-mock-plugin
|
|
Success! Enabled the my-mock-plugin plugin at: my-secrets-plugin/
|
|
```
|
|
|
|
If you try to mount this particular plugin as an auth method instead of a
|
|
secrets engine, you will get an error:
|
|
|
|
```shell-session
|
|
$ vault auth enable -path=my-auth-plugin my-mock-plugin
|
|
# ...
|
|
* cannot mount 'my-mock-plugin' of type 'secret' as an auth method
|
|
```
|
|
|
|
## Perform Operations
|
|
|
|
Each plugin responds to read, write, list, and delete as its own behavior.
|
|
|
|
```shell-session
|
|
$ vault write my-secrets-plugin/kv/foo value=bar
|
|
Key Value
|
|
--- -----
|
|
value bar
|
|
```
|
|
|
|
## Disable Plugin
|
|
|
|
When you are done using the plugin, disable it.
|
|
|
|
```shell-session
|
|
$ vault secrets disable my-secrets-plugin
|
|
Success! Disabled the secrets engine (if it existed) at: my-secrets-plugin/
|
|
```
|
|
|
|
[plugin-system]: /docs/internals/plugins
|
|
[database-backend]: /docs/secrets/databases
|