From 85967cb5a837de0e407eea56adac88a4d2b81981 Mon Sep 17 00:00:00 2001 From: Brian Kassouf Date: Wed, 3 May 2017 00:01:28 -0700 Subject: [PATCH] Add custom plugins docs page --- .../docs/secrets/databases/cassandra.html.md | 2 +- .../docs/secrets/databases/custom.html.md | 120 ++++++++++++++++++ .../docs/secrets/databases/mssql.html.md | 2 +- .../secrets/databases/mysql-maria.html.md | 2 +- .../docs/secrets/databases/postgresql.html.md | 2 +- website/source/layouts/docs.erb | 3 + 6 files changed, 127 insertions(+), 4 deletions(-) create mode 100644 website/source/docs/secrets/databases/custom.html.md diff --git a/website/source/docs/secrets/databases/cassandra.html.md b/website/source/docs/secrets/databases/cassandra.html.md index 99d3d3bf97..b3d87f7ed2 100644 --- a/website/source/docs/secrets/databases/cassandra.html.md +++ b/website/source/docs/secrets/databases/cassandra.html.md @@ -58,5 +58,5 @@ The full list of configurable options can be seen in the [Cassandra database plugin API](/api/secret/database/cassandra.html) page. Or for more information on the Database secret backend's HTTP API please see the [Database secret -backend API](/api/secret/database/index.html). +backend API](/api/secret/database/index.html) page. diff --git a/website/source/docs/secrets/databases/custom.html.md b/website/source/docs/secrets/databases/custom.html.md new file mode 100644 index 0000000000..5911e1d809 --- /dev/null +++ b/website/source/docs/secrets/databases/custom.html.md @@ -0,0 +1,120 @@ +--- +layout: "docs" +page_title: "Custom Database Plugins" +sidebar_current: "docs-secrets-databases-custom" +description: |- + Creating custom database plugins for Vault's Database backend to generate credentials for a database. +--- + +# Custom Database Plugins + +The Database backend allows new functionality to be added through a plugin +interface without needing to modify vault's core code. This allows you write +your own code to generate credentials in any database you wish. It also allows +databases that require dynamically linked libraries to be used with vault. + +~> **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. + +Please read the [Plugins internals](/docs/internals/plugins.html) docs for more +information about the plugin system before getting started building your +Database plugin. + +## Plugin Interface + +All plugins for the Database backend must implement the same simple interface. + +```go +type Database interface { + Type() (string, error) + CreateUser(statements Statements, usernamePrefix string, expiration time.Time) (username string, password string, err error) + RenewUser(statements Statements, username string, expiration time.Time) error + RevokeUser(statements Statements, username string) error + + Initialize(config map[string]interface{}, verifyConnection bool) error + Close() error +} +``` + +You'll notice the first parameter to a number of those functions is a +`Statements` struct. This struct is used to pass the Role's configured +statements to the plugin on function call. The struct is defined as: + +```go +type Statements struct { + CreationStatements string + RevocationStatements string + RollbackStatements string + RenewStatements string +} +``` + +It is up to your plugin to replace the `{{name}}`, `{{password}}`, and +`{{expiration}}` in these statements with the proper vaules. + +The `Initialize` function is passed a map of keys to values, this data is what the +user specified as the configuration for the plugin. Your plugin should use this +data to make connections to the database. It is also passed a boolean value +specifying whether or not your plugin should return an error if it is unable to +connect to the database. + +## Serving your plugin + +Once your plugin is built you should pass it to vault's `plugins` package by +calling the `Serve` method: + +```go +package main + +import ( + "github.com/hashicorp/vault/plugins" +) + +func main() { + plugins.Serve(new(MyPlugin), nil) +} +``` + +Replacing `MyPlugin` with the actual implementation of your plugin. + +The second parameter to `Serve` takes in an optional vault `api.TLSConfig` for +configuring the plugin to communicate with vault for the initial unwrap call. +This if useful if your vault setup requires client certificate checks. This +config wont be used once the plugin unwraps its own TLS cert and key. + +## Running your plugin + +The above main package, once built, will supply you with a binary of your +plugin. We also recommend if you are planning on distributing your plugin to +build with [gox](https://github.com/mitchellh/gox) for cross platform builds. + +To use your plugin with the Database backend you need to place the binary in the +plugin directory as specified in the [plugin internals](/docs/internals/plugins.html) docs. + +You should now be able to register your plugin into the vault catalog. To do +this your token will need sudo permissions. + +``` +$ vault write sys/plugins/catalog/myplugin-database-plugin \ + sha_256= \ + command="myplugin" +Success! Data written to: sys/plugins/catalog/myplugin-database-plugin +``` + +Now you should be able to configure your plugin like any other: + +``` +$ vault write database/config/myplugin \ + plugin_name=myplugin-database-plugin \ + allowed_roles="readonly" \ + myplugins_connection_details=.... + +The following warnings were returned from the Vault server: +* Read access to this endpoint should be controlled via ACLs as it will return the connection details as is, including passwords, if any. +``` + + + + diff --git a/website/source/docs/secrets/databases/mssql.html.md b/website/source/docs/secrets/databases/mssql.html.md index 2d220ddb87..0eefe17642 100644 --- a/website/source/docs/secrets/databases/mssql.html.md +++ b/website/source/docs/secrets/databases/mssql.html.md @@ -56,5 +56,5 @@ The full list of configurable options can be seen in the [MSSQL database plugin API](/api/secret/database/mssql.html) page. Or for more information on the Database secret backend's HTTP API please see the [Database secret -backend API](/api/secret/database/index.html). +backend API](/api/secret/database/index.html) page. diff --git a/website/source/docs/secrets/databases/mysql-maria.html.md b/website/source/docs/secrets/databases/mysql-maria.html.md index bd61cc43b5..76ca193fcf 100644 --- a/website/source/docs/secrets/databases/mysql-maria.html.md +++ b/website/source/docs/secrets/databases/mysql-maria.html.md @@ -54,5 +54,5 @@ The full list of configurable options can be seen in the [MySQL database plugin API](/api/secret/database/mysql.html) page. Or for more information on the Database secret backend's HTTP API please see the [Database secret -backend API](/api/secret/database/index.html). +backend API](/api/secret/database/index.html) page. diff --git a/website/source/docs/secrets/databases/postgresql.html.md b/website/source/docs/secrets/databases/postgresql.html.md index e5fee10ef0..81716132f5 100644 --- a/website/source/docs/secrets/databases/postgresql.html.md +++ b/website/source/docs/secrets/databases/postgresql.html.md @@ -56,5 +56,5 @@ The full list of configurable options can be seen in the [PostgreSQL database plugin API](/api/secret/database/postgresql.html) page. Or for more information on the Database secret backend's HTTP API please see the [Database secret -backend API](/api/secret/database/index.html). +backend API](/api/secret/database/index.html) page. diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index a6afd9c2d9..95787e8e19 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -234,6 +234,9 @@ > PostgreSQL + > + Custom +