diff --git a/website/source/api/system/plugins-backend-reload.html.md b/website/source/api/system/plugins-backend-reload.html.md new file mode 100644 index 000000000000..8b5fe6a18e35 --- /dev/null +++ b/website/source/api/system/plugins-backend-reload.html.md @@ -0,0 +1,47 @@ +--- +layout: "api" +page_title: "/sys/plugins/backend/reload - HTTP API" +sidebar_current: "docs-http-system-plugins-backend-reload" +description: |- + The `/sys/plugins/backend/reload` endpoint is used to reload plugin backends. +--- + +# `/sys/plugins/backend/reload` + +The `/sys/plugins/backend/reload` endpoint is used to reload mounted plugin +backends. Either the plugin name (`plugin`) or the desired plugin backend mounts +(`mounts`) must be provided, but not both. In the case that the plugin name is +provided, all mounted paths that use that plugin backend will be reloaded. + +## Reload Plugins + +This endpoint reloads mounted plugin backends. + +| Method | Path - | Produces | +| :------- | :---------------------------- | :--------------------- | +| `PUT` | `/sys/plugins/backend/reload` | `204 (empty body)` | + +### Parameters + +- `plugin` `(string: "")` – The name of the plugin to reload, as + registered in the plugin catalog. + +- `mounts` `(slice: [])` – Array or comma separated string mount paths + of the plugin backends to reload. + +### Sample Payload + +```json +{ + "plugin": "mock-plugin" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request PUT + https://vault.rocks/v1/sys/backends/reload +``` \ No newline at end of file diff --git a/website/source/docs/internals/plugins.html.md b/website/source/docs/internals/plugins.html.md index 02f151249189..609ffbde8a9e 100644 --- a/website/source/docs/internals/plugins.html.md +++ b/website/source/docs/internals/plugins.html.md @@ -26,11 +26,14 @@ 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 +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 unique generated TLS certificate and -private key for it to use to talk to the original vault process. +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. + +~> 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 @@ -70,7 +73,6 @@ $ vault write sys/plugins/catalog/myplugin-database-plugin \ 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 @@ -79,6 +81,11 @@ the catalog, sending along the JWT formatted response wrapping token and mlock settings (like Vault, plugins support the use of mlock when available). # 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, @@ -89,10 +96,6 @@ 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.) -~> 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. - 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). diff --git a/website/source/guides/plugin-backends.html.md b/website/source/guides/plugin-backends.html.md new file mode 100644 index 000000000000..f45a699f2ea6 --- /dev/null +++ b/website/source/guides/plugin-backends.html.md @@ -0,0 +1,103 @@ +--- +layout: "guides" +page_title: "Plugin Backends - Guides" +sidebar_current: "guides-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 secret and auth backends to be mounted. + +It is worth noting that even though [database backend][database-backend] +operates under the same underlying plugin mechanism, it is slightly different +in design than plugin backends demonstrated in this guide. The database backend +manages multiple plugins under the same backend mount point, whereas plugin +backends are generic backends that function as either secret or auth backends. + +This guide provides steps to build, register, and mount non-database external +plugin backends. + +## Setting up Vault + +Set `plugin_directory` to the desired path in the Vault configuration file. +The path should exist and have proper lockdown on access permissions. + +``` +$ cat vault-config.hcl +... +plugin_directory="/etc/vault/vault_plugins" +... +``` + +## Build the Plugin Backend + +Build the custom backend binary, and move it to the `plugin_directory` path. +In this guide, we will use `mock-plugin` that comes from Vault's +`logical/plugin/mock` package. + +``` +$ ls . +main.go + +$ ls .. +backend.go backend_test.go mock-plugin/ path_internal.go path_kv.go + +$ go build -o mock-plugin main.go + +$ mv mock-plugin /etc/vault/vault_plugins +``` + +## Register the Plugin Into the Plugin Catalog + +Start the Vault server. Find out the sha256 sum of the compiled plugin binary, +and use that to register the plugin into Vault's plugin catalog. + +``` +$ shasum -a 256 ~/code/tmp/vault_plugins/mock-plugin +2c071aafa1b30897e60b79643e77592cb9d1e8f803025d44a7f9bbfa4779d615 /etc/vault/vault_plugins/mock-plugin + +$ vault sys/plugins/catalog/mock-plugin sha_256=2c071aafa1b30897e60b79643e77592cb9d1e8f803025d44a7f9bbfa4779d615 command=mock-plugin +Success! Data written to: sys/plugins/catalog/mock-plugin +``` + +## Mount the Plugin + +``` +$ vault mount -path=mock -plugin-name=mock-plugin plugin +Successfully mounted plugin 'mock-plugin' at 'mock'! + +$ vault mounts +Path Type Accessor Plugin Default TTL Max TTL Force No Cache Replication Behavior Description +cubbyhole/ cubbyhole cubbyhole_80ef4e30 n/a n/a n/a false local per-token private secret storage +mock/ plugin plugin_10fc2cce mock-plugin system system false replicated +secret/ generic generic_ef2a14ec n/a system system false replicated generic secret storage +sys/ system system_e3a4cccd n/a n/a n/a false replicated system endpoints used for control, policy and debugging +``` + +## Perform operations on the mount + +``` +$ vault write mock/kv/foo value=bar +Key Value +--- ----- +value bar +``` + +## Unmount the plugin + +``` +$ vault unmount mock +Successfully unmounted 'mock' if it was mounted + +$ vault mounts +Path Type Accessor Plugin Default TTL Max TTL Force No Cache Replication Behavior Description +cubbyhole/ cubbyhole cubbyhole_80ef4e30 n/a n/a n/a false local per-token private secret storage +secret/ generic generic_ef2a14ec n/a system system false replicated generic secret storage +sys/ system system_e3a4cccd n/a n/a n/a false replicated system endpoints used for control, policy and debugging +``` + +[plugin-system]: docs/internals/plugins.html +[database-backend]: docs/secrets/databases/index.html \ No newline at end of file diff --git a/website/source/layouts/api.erb b/website/source/layouts/api.erb index 0e54de6dc28f..140ad7e11ffd 100644 --- a/website/source/layouts/api.erb +++ b/website/source/layouts/api.erb @@ -179,6 +179,9 @@ > /sys/mounts + > + /sys/plugins/backend/reload + > /sys/plugins/catalog diff --git a/website/source/layouts/guides.erb b/website/source/layouts/guides.erb index 73e4c642ac7e..0b4693b2459a 100644 --- a/website/source/layouts/guides.erb +++ b/website/source/layouts/guides.erb @@ -17,6 +17,10 @@ Replication Setup & Guidance + > + Building Plugin Backends + +
>