Skip to main content

External plugin architecture

OpenBao's external plugins are completely separate, standalone applications that OpenBao executes and communicates with over RPC. This means the plugin process does not share the same memory space as OpenBao and therefore can only access the interfaces and arguments given to it. This also means a crash in a plugin cannot crash the entirety of OpenBao.

It is possible to enable a custom plugin with a name that's identical to a built-in plugin. In such a situation, OpenBao will always choose the custom plugin when enabling it.

External plugin lifecycle​

OpenBao external plugins are long-running processes that remain running once they are spawned by OpenBao, the parent process. Plugin processes can be started by OpenBao's active node. Additionally, there are cases where plugin processes may be terminated by OpenBao. These cases include, but are not limited to:

  • OpenBao active node step-down
  • OpenBao barrier seal
  • OpenBao graceful shutdown
  • Disabling a Secrets Engine or Auth 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

The lifecycle of plugin processes are managed automatically by OpenBao. Termination of these processes are typical in certain scenarios, such as the ones listed above. OpenBao will start plugin processes when they are enabled. A plugin process may be started or terminated through other internal processes within OpenBao as well. Since OpenBao manages and tracks the lifecycle of its plugins, these processes should not be terminated by anything other than OpenBao. If a plugin process is shutdown out-of-band, the plugin process will be lazily loaded when a request that requires the plugin is received by OpenBao.

Plugin communication​

OpenBao communicates with external plugins over RPC. To secure this communication, OpenBao creates a mutually authenticated TLS connection with the plugin's RPC server. Plugins make use of the AutoMTLS feature of go-plugin which will automatically negotiate mutual TLS for transport authentication.

The api_addr must be set in order for the plugin process to establish communication with the OpenBao server during mount time. If the storage backend has HA enabled and supports automatic host address detection, OpenBao will automatically attempt to determine the api_addr as well.

Plugin registration​

An important consideration of OpenBao's plugin system is to ensure the plugin invoked by OpenBao is authentic and maintains integrity. There are two components that an OpenBao operator needs to configure before external plugins can be run- the plugin directory and the plugin catalog entry.

Plugin directory​

The plugin directory is a configuration option of OpenBao and can be specified in the configuration file. This setting specifies a directory in which all plugin binaries must live; this value cannot be a symbolic link. A plugin cannot be added to OpenBao unless it exists in the plugin directory. There is no default for this configuration option, and if it is not set, plugins cannot be added to OpenBao.

Enabling the file permissions check via the environment variable VAULT_ENABLE_FILE_PERMISSIONS_CHECK allows OpenBao to check if the config directory and files are owned by the user running OpenBao. It also checks if there are no write or execute permissions for group or others. OpenBao allows operators to specify the user and permissions of the plugin directory and binaries using parameters plugin_file_uid and plugin_file_permissions in config if an operator needs those to be different. This check is disabled by default.

Plugin catalog​

The plugin catalog is OpenBao's list of approved plugins. The catalog is stored in OpenBao's barrier and can only be updated by an OpenBao user with sudo permissions. Upon adding a new plugin, the plugin name, SHA256 sum of the executable, and the command that should be used to run the plugin must be provided. The catalog will ensure the executable referenced in the command exists in the plugin directory. When added to the catalog, the plugin is not automatically executed, but becomes visible to backends and can be executed by them. For more information on the plugin catalog please see the Plugin Catalog API docs.

An example of plugin registration in current versions of OpenBao:

$ bao plugin register -sha256=<SHA256 Hex value of the plugin binary> \
    secret \                  # type
    myplugin-database-plugin

Success! Registered plugin: 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 configured in the plugin catalog. Finally OpenBao runs the command configured in the catalog, sending along the JWT formatted response wrapping token.

Plugin upgrades​

External plugins may be updated by registering and reloading them. More details on the upgrade procedure can be found in Upgrading OpenBao Plugins.

Plugin multiplexing​

To avoid spawning multiple plugin processes for mounts of the same type, plugins can implement plugin multiplexing. This allows a single plugin process to be used for multiple mounts of a given type. This single process will be multiplexed across all OpenBao 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 OpenBao's respective plugin or dbplugin SDK packages. 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 Serve function.

More resources on implementing plugin multiplexing: