hashicorp · fairclothjm · Mar 22, 2022 · Mar 15, 2022 · Mar 15, 2022 · Mar 15, 2022
@@ -180,7 +180,7 @@ method as an external plugin. The azure plugin method is integrated into Vault a
 a builtin method by default.
 
 Assuming you have saved the binary `vault-plugin-auth-azure` to some folder and
-configured the [plugin directory](/docs/internals/plugins#plugin-directory)
+configured the [plugin directory](/docs/plugins/plugin-architecture#plugin-directory)
 for your server at `path/to/plugins`:
 
 1. Enable the plugin in the catalog:

@@ -104,7 +104,7 @@ to specify where the configuration is.
 
   ~> Note: Since each plugin runs as a separate process, you need to do the same
   for each plugin in your [plugins
-  directory](/docs/internals/plugins#plugin-directory).
+  directory](/docs/plugins/plugin-architecture#plugin-directory).
 
   If you use a Linux distribution with a modern version of systemd, you can add
   the following directive to the "[Service]" configuration section:

@@ -288,7 +288,7 @@ are a function of the alphabet size.
 
 ### External plugin limits
 
-The [plugin system](/docs/internals/plugins) launches a separate process
+The [plugin system](/docs/plugins) launches a separate process
 initiated by Vault that communicates over RPC. For each secret engine and auth
 method that's enabled as an external plugin, Vault will spawn a process on the
 host system. For the Database Secrets Engines, external database plugins will

@@ -16,7 +16,7 @@ This program is intended to be largely a self-service process with links and gui
 
 Vault is an Identity-based security solution that leverages trusted sources of identity to keep secrets and application data secured with one centralized, audited workflow for tightly controlling access to secrets across applications, systems, and infrastructure while encrypting data both in flight and at rest. For a full description of the current features please refer to the Vault [website](/). 
 
-Vault has a secure [plugin](/docs/internals/plugins) 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.
+Vault has a secure [plugin](/docs/plugins) 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.
 
 Vault plugins can be built-in and bundled with the Vault binary, or be external that has to be manually mounted. Built-in plugins are developed by HashiCorp, while external plugins can be developed by HashiCorp, technology partners, or the community. There is a curated collection of all plugins, both built-in and external, located on the [Plugin Portal](/docs/plugin-portal).
 

@@ -0,0 +1,38 @@
+---
+layout: docs
+page_title: Plugin System
+description: Learn about Vault's plugin system.
+---
+
+
+# Plugin System
+
+All Vault auth methods and secrets engines 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 location, 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, the plugin must be
+run as an external plugin.
+
+## External Plugins
+
+External plugins are not shipped with Vault and require additional operator
+intervention to run.
+
+To run an external plugin, a binary of the plugin is required. Plugin
+binaries can be obtained from [releases.hashicorp.com](https://releases.hashicorp.com/)
+or they can be [built from source](/docs/plugins/plugin-development#building-a-plugin-from-source).
+
+Vault's external plugins are completely separate, standalone applications that
+Vault executes and communicates with over RPC. Each time a Vault secret engine
+or auth method is mounted, a new process is spawned. However, database plugins
+can be made to implement [plugin multiplexing](/docs/plugins/plugin-architecture#plugin-multiplexing)
+which allows a single plugin process to be used for multiple database
+connections.
@@ -1,33 +1,12 @@
 ---
 layout: docs
-page_title: Plugin System
-description: Learn about Vault's plugin system.
+page_title: External Plugin Architecture
+description: Learn about Vault's plugin architecture.
 ---
 
-# Plugin System
+# External Plugin Architecture
 
-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
+Vault's external 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
@@ -37,9 +16,9 @@ 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
+## External Plugin Lifecycle
 
-Vault plugins are long-running processes that remain running once they are
+Vault external 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
@@ -67,17 +46,17 @@ 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'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.
+The [api_addr](/docs/configuration#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: Prior to Vault version 1.9.2, reading the original connection's TLS
 connection state is not supported in plugins.
@@ -144,21 +123,40 @@ 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.
+~> Note: If Vault is configured with `mlock` enabled, then the Vault executable
+and each plugin executable in your [plugins directory](/docs/plugins/plugin-architecture#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).
+External 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
+## Plugin Multiplexing
+
+Database plugins can be made to implement plugin multiplexing
+which allows a single plugin process to be used for multiple database
+connections. This single process, per database plugin, will be multiplexed
+across all Vault namespaces for mounts of this type. Multiplexing a plugin
+does not affect the current behavior of existing plugins.
+
+To enable multiplexing, the plugin must be compiled with the `ServeMultiplex`
+function call from Vault's `dbplugin` package. At this time, there is no
+opt-out capability for plugins that implement multiplexing. To use a
+non-multiplexed plugin, run an older version of the plugin. i.e. the
+plugin calls the `dbplugin.Serve` function. More details
+on implementing plugin multiplexing can be found in
+[Upgrading Vault Plugins](/docs/secrets/databases/custom#serving-a-plugin-with-multiplexing).
+
+## Troubleshooting
 
 #### Unrecognized remote plugin message
 
 If the following error is encountered when enabling a plugin secret engine or
 auth method:
+
+<CodeBlockConfig hideClipboard>
 
 ```sh
 Unrecognized remote plugin message:
@@ -167,90 +165,12 @@ This usually means that the plugin is either invalid or simply
 needs to be recompiled to support the latest protocol.
 ```
 
+</CodeBlockConfig>
+
 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)
-	}
-}
+```shell-session
+$ sudo setcap cap_ipc_lock=+ep <plugin-binary>
 ```
 
-And that's basically it! You would just need to change `myPlugin` to your actual
-plugin.
-
-[api_addr]: /docs/configuration#api_addr
-
-## Plugin Development - Resources
-
-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.
-
-Other HashiCorp plugin development resources:
-
-* [vault-auth-plugin-example](https://github.com/hashicorp/vault-auth-plugin-example)
-
-### Plugin Development - Resources - Community
-
-Community plugin examples/guides are developed by community members. HashiCorp
-does not validate these for correctness.
-
- - [Enigma (good starting point)](https://github.com/ixe013/benigma)
-
-Authors who wish to have their guides or examples listed may file a submission
-via a GitHub issue or directly open a pull request with changes to this page.