diff --git a/website/source/api/secret/databases/cassandra.html.md b/website/source/api/secret/databases/cassandra.html.md new file mode 100644 index 000000000..5e2b5a836 --- /dev/null +++ b/website/source/api/secret/databases/cassandra.html.md @@ -0,0 +1,96 @@ +--- +layout: "api" +page_title: "Cassandra Database Plugin - HTTP API" +sidebar_current: "docs-http-secret-databases-cassandra-maria" +description: |- + The Cassandra plugin for Vault's Database backend generates database credentials to access Cassandra servers. +--- + +# Cassandra Database Plugin HTTP API + +The Cassandra Database Plugin is one of the supported plugins for the Database +backend. This plugin generates database credentials dynamically based on +configured roles for the Cassandra database. + +## Configure Connection + +In addition to the parameters defined by the [Database +Backend](/api/secret/databases/index.html#configure-connection), this plugin +has a number of parameters to further configure a connection. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/database/config/:name` | `204 (empty body)` | + +### Parameters +- `hosts` `(string: )` – Specifies a set of comma-delineated Cassandra + hosts to connect to. + +- `username` `(string: )` – Specifies the username to use for + superuser access. + +- `password` `(string: )` – Specifies the password corresponding to + the given username. + +- `tls` `(bool: true)` – Specifies whether to use TLS when connecting to + Cassandra. + +- `insecure_tls` `(bool: false)` – Specifies whether to skip verification of the + server certificate when using TLS. + +- `pem_bundle` `(string: "")` – Specifies concatenated PEM blocks containing a + certificate and private key; a certificate, private key, and issuing CA + certificate; or just a CA certificate. + +- `pem_json` `(string: "")` – Specifies JSON containing a certificate and + private key; a certificate, private key, and issuing CA certificate; or just a + CA certificate. For convenience format is the same as the output of the + `issue` command from the `pki` backend; see + [the pki documentation](/docs/secrets/pki/index.html). + +- `protocol_version` `(int: 2)` – Specifies the CQL protocol version to use. + +- `connect_timeout` `(string: "5s")` – Specifies the connection timeout to use. + +TLS works as follows: + +- If `tls` is set to true, the connection will use TLS; this happens + automatically if `pem_bundle`, `pem_json`, or `insecure_tls` is set + +- If `insecure_tls` is set to true, the connection will not perform verification + of the server certificate; this also sets `tls` to true + +- If only `issuing_ca` is set in `pem_json`, or the only certificate in + `pem_bundle` is a CA certificate, the given CA certificate will be used for + server certificate verification; otherwise the system CA certificates will be + used + +- If `certificate` and `private_key` are set in `pem_bundle` or `pem_json`, + client auth will be turned on for the connection + +`pem_bundle` should be a PEM-concatenated bundle of a private key + client +certificate, an issuing CA certificate, or both. `pem_json` should contain the +same information; for convenience, the JSON format is the same as that output by +the issue command from the PKI backend. + +### Sample Payload + +```json +{ + "plugin_name": "cassandra-database-plugin", + "allowed_roles": "readonly", + "hosts": "cassandra1.local", + "username": "user", + "password": "pass" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/cassandra/config/connection +``` diff --git a/website/source/api/secret/databases/index.html.md b/website/source/api/secret/databases/index.html.md new file mode 100644 index 000000000..9e6015648 --- /dev/null +++ b/website/source/api/secret/databases/index.html.md @@ -0,0 +1,342 @@ +--- +layout: "api" +page_title: "Databases - HTTP API" +sidebar_current: "docs-http-secret-databases" +description: |- + Top page for database secret backend information +--- + +# Database Secret Backend HTTP API + +This is the API documentation for the Vault Database secret backend. For +general information about the usage and operation of the Database backend, +please see the +[Vault Database backend documentation](/docs/secrets/database/index.html). + +This documentation assumes the Database backend is mounted at the +`/database` path in Vault. Since it is possible to mount secret backends at +any location, please update your API calls accordingly. + +## Configure Connection + +This endpoint configures the connection string used to communicate with the +desired database. In addition to the parameters listed here, each Database +plugin has additional, database plugin specifig, parameters for this endpoint. +Please read the HTTP API for the plugin you'd wish to configure to see the full +list of additional parameters. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/database/config/:name` | `204 (empty body)` | + +### Parameters +- `name` `(string: )` – Specifies the name for this database + connection. This is specified as part of the URL. + +- `plugin_name` `(string: )` - Specifies the name of the plugin to use + for this connection. + +- `verify_connection` `(bool: true)` – Specifies if the connection is verified + during initial configuration. Defaults to true. + +- `allowed_roles` `(slice: [])` - Array or comma separated string of the roles + allowed to use this connection. Defaults to empty (no roles), if contains a + "*" any role can use this connection. + +### Sample Payload + +```json +{ + "plugin_name": "mysql-database-plugin", + "allowed_roles": "readonly", + "connection_url": "root:mysql@tcp(127.0.0.1:3306)/" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/database/config/mysql +``` + +## Read Connection + +This endpoint returns the configuration settings for a connection. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/database/config/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the connection to read. + This is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + https://vault.rocks/v1/database/config/mysql +``` + +### Sample Response + +```json +{ + "data": { + "allowed_roles": [ + "readonly" + ], + "connection_details": { + "connection_url": "root:mysql@tcp(127.0.0.1:3306)/", + }, + "plugin_name": "mysql-database-plugin" + }, +} +``` + +## Delete Connection + +This endpoint deletes a connection. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/database/config/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the connection to delete. + This is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/database/config/mysql +``` + +## Reset Connection + +This endpoint closes a connection and it's underlying plugin and restarts it +with the configuration stored in the barrier. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/database/reset/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the connection to delete. + This is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + https://vault.rocks/v1/database/reset/mysql +``` + +## Create Role + +This endpoint creates or updates a role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/database/roles/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to create. This + is specified as part of the URL. + +- `db_name` `(string: )` - The name of the database connection to use + for this role. + +- `default_ttl` `(string: )` - Specifies the TTL for the lease + associated with this role. + +- `max_ttl` `(string: )` - Specifies the maximum TTL for the lease + associated with this role. + +- `creation_statements` `(string: )` – Specifies the database + statements executed to create and configure a user. Must be a + semicolon-separated string, a base64-encoded semicolon-separated string, a + serialized JSON string array, or a base64-encoded serialized JSON string + array. The '{{name}}', '{{password}}' and '{{expiration}}' values will be + substituted. + +- `revocation_statements` `(string: "")` – Specifies the database statements to + be executed to revoke a user. Must be a semicolon-separated string, a + base64-encoded semicolon-separated string, a serialized JSON string array, or + a base64-encoded serialized JSON string array. The '{{name}}' value will be + substituted. + +- `rollback_statements` `(string: "")` – Specifies the database statements to be + executed rollback a create operation in the event of an error. Not every + plugin type will support this functionality. Must be a semicolon-separated + string, a base64-encoded semicolon-separated string, a serialized JSON string + array, or a base64-encoded serialized JSON string array. The '{{name}}' value + will be substituted. + +- `renew_statements` `(string: "")` – Specifies the database statements to be + executed to renew a user. Not every plugin type will support this + functionality. Must be a semicolon-separated string, a base64-encoded + semicolon-separated string, a serialized JSON string array, or a + base64-encoded serialized JSON string array. The '{{name}}' and + '{{expiration}}` values will be substituted. + + +### Sample Payload + +```json +{ + "db_name": "mysql", + "creation_statements": "CREATE USER '{{name}}'@'%' IDENTIFIED BY '{{password}}';GRANT SELECT ON *.* TO '{{name}}'@'%';", + "default_ttl": "1h", + "max_ttl": "24h" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/database/roles/my-role +``` + +## Read Role + +This endpoint queries the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/database/roles/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to read. This + is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/database/roles/my-role +``` + +### Sample Response + +```json +{ + "data": { + "creation_statements": "CREATE ROLE \"{{name}}\" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}'; GRANT SELECT ON ALL TABLES IN SCHEMA public TO \"{{name}}\";", + "db_name": "mysql", + "default_ttl": 3600, + "max_ttl": 86400, + "renew_statements": "", + "revocation_statements": "", + "rollback_statements": "" + }, +} +``` + +## List Roles + +This endpoint returns a list of available roles. Only the role names are +returned, not any values. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/database/roles` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://vault.rocks/v1/database/roles +``` + +### Sample Response + +```json +{ + "auth": null, + "data": { + "keys": ["dev", "prod"] + }, + "lease_duration": 2764800, + "lease_id": "", + "renewable": false +} +``` + +## Delete Role + +This endpoint deletes the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/database/roles/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to delete. This + is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/database/roles/my-role +``` + +## Generate Credentials + +This endpoint generates a new set of dynamic credentials based on the named +role. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/database/creds/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to create + credentials against. This is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/database/creds/my-role +``` + +### Sample Response + +```json +{ + "data": { + "username": "root-1430158508-126", + "password": "132ae3ef-5a64-7499-351e-bfe59f3a2a21" + } +} +``` diff --git a/website/source/api/secret/databases/mssql.html.md b/website/source/api/secret/databases/mssql.html.md new file mode 100644 index 000000000..09893df45 --- /dev/null +++ b/website/source/api/secret/databases/mssql.html.md @@ -0,0 +1,60 @@ +--- +layout: "api" +page_title: "MSSQL Database Plugin - HTTP API" +sidebar_current: "docs-http-secret-databases-mssql-maria" +description: |- + The MSSQL plugin for Vault's Database backend generates database credentials to access MSSQL servers. +--- + +# MSSQL Database Plugin HTTP API + +The MSSQL Database Plugin is one of the supported plugins for the Database +backend. This plugin generates database credentials dynamically based on +configured roles for the MSSQL database. + +## Configure Connection + +In addition to the parameters defined by the [Database +Backend](/api/secret/databases/index.html#configure-connection), this plugin +has a number of parameters to further configure a connection. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/database/config/:name` | `204 (empty body)` | + +### Parameters +- `connection_url` `(string: )` - Specifies the MSSQL DSN. + +- `max_open_connections` `(int: 2)` - Speficies the name of the plugin to use + for this connection. + +- `max_idle_connections` `(int: 0)` - Specifies the maximum number of idle + connections to the database. A zero uses the value of `max_open_connections` + and a negative value disables idle connections. If larger than + `max_open_connections` it will be reduced to be equal. + +- `max_connection_lifetime` `(string: "0s")` - Specifies the maximum amount of + time a connection may be reused. If <= 0s connections are reused forever. + +### Sample Payload + +```json +{ + "plugin_name": "mssql-database-plugin", + "allowed_roles": "readonly", + "connection_url": "sqlserver://sa:yourStrong(!)Password@localhost:1433", + "max_open_connections": 5, + "max_connection_lifetime": "5s", +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/database/config/mssql +``` + diff --git a/website/source/api/secret/databases/mysql-maria.html.md b/website/source/api/secret/databases/mysql-maria.html.md new file mode 100644 index 000000000..981506798 --- /dev/null +++ b/website/source/api/secret/databases/mysql-maria.html.md @@ -0,0 +1,60 @@ +--- +layout: "api" +page_title: "MySQL/MariaDB Database Plugin - HTTP API" +sidebar_current: "docs-http-secret-databases-mysql-maria" +description: |- + The MySQL/MariaDB plugin for Vault's Database backend generates database credentials to access MySQL and MariaDB servers. +--- + +# MySQL/MariaDB Database Plugin HTTP API + +The MySQL Database Plugin is one of the supported plugins for the Database +backend. This plugin generates database credentials dynamically based on +configured roles for the MySQL database. + +## Configure Connection + +In addition to the parameters defined by the [Database +Backend](/api/secret/databases/index.html#configure-connection), this plugin +has a number of parameters to further configure a connection. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/database/config/:name` | `204 (empty body)` | + +### Parameters +- `connection_url` `(string: )` - Specifies the MySQL DSN. + +- `max_open_connections` `(int: 2)` - Speficies the name of the plugin to use + for this connection. + +- `max_idle_connections` `(int: 0)` - Specifies the maximum number of idle + connections to the database. A zero uses the value of `max_open_connections` + and a negative value disables idle connections. If larger than + `max_open_connections` it will be reduced to be equal. + +- `max_connection_lifetime` `(string: "0s")` - Specifies the maximum amount of + time a connection may be reused. If <= 0s connections are reused forever. + +### Sample Payload + +```json +{ + "plugin_name": "mysql-database-plugin", + "allowed_roles": "readonly", + "connection_url": "root:mysql@tcp(127.0.0.1:3306)/" + "max_open_connections": 5, + "max_connection_lifetime": "5s", +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/database/config/mysql +``` + diff --git a/website/source/api/secret/databases/postgresql.html.md b/website/source/api/secret/databases/postgresql.html.md new file mode 100644 index 000000000..5ff6b8022 --- /dev/null +++ b/website/source/api/secret/databases/postgresql.html.md @@ -0,0 +1,60 @@ +--- +layout: "api" +page_title: "PostgreSQL Database Plugin - HTTP API" +sidebar_current: "docs-http-secret-databases-postgresql-maria" +description: |- + The PostgreSQL plugin for Vault's Database backend generates database credentials to access PostgreSQL servers. +--- + +# PostgreSQL Database Plugin HTTP API + +The PostgreSQL Database Plugin is one of the supported plugins for the Database +backend. This plugin generates database credentials dynamically based on +configured roles for the PostgreSQL database. + +## Configure Connection + +In addition to the parameters defined by the [Database +Backend](/api/secret/databases/index.html#configure-connection), this plugin +has a number of parameters to further configure a connection. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/database/config/:name` | `204 (empty body)` | + +### Parameters +- `connection_url` `(string: )` - Specifies the PostgreSQL DSN. + +- `max_open_connections` `(int: 2)` - Speficies the name of the plugin to use + for this connection. + +- `max_idle_connections` `(int: 0)` - Specifies the maximum number of idle + connections to the database. A zero uses the value of `max_open_connections` + and a negative value disables idle connections. If larger than + `max_open_connections` it will be reduced to be equal. + +- `max_connection_lifetime` `(string: "0s")` - Specifies the maximum amount of + time a connection may be reused. If <= 0s connections are reused forever. + +### Sample Payload + +```json +{ + "plugin_name": "postgresql-database-plugin", + "allowed_roles": "readonly", + "connection_url": "postgresql://root:root@localhost:5432/postgres", + "max_open_connections": 5, + "max_connection_lifetime": "5s", +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/database/config/postgresql +``` + diff --git a/website/source/docs/secrets/databases/custom.html.md b/website/source/docs/secrets/databases/custom.html.md index 5911e1d80..7d21a19c9 100644 --- a/website/source/docs/secrets/databases/custom.html.md +++ b/website/source/docs/secrets/databases/custom.html.md @@ -11,7 +11,8 @@ description: |- 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. +databases that require dynamically linked libraries to be used as plugins while +keeping Vault itself statically linked. ~> **Advanced topic!** Plugin development is a highly advanced topic in Vault, and is not required knowledge for day-to-day usage. @@ -81,7 +82,7 @@ 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 +This is 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 diff --git a/website/source/layouts/api.erb b/website/source/layouts/api.erb index c209937bc..ea8e35624 100644 --- a/website/source/layouts/api.erb +++ b/website/source/layouts/api.erb @@ -21,7 +21,7 @@ AWS > - Cassandra + Cassandra (Deprecated) > Consul @@ -29,6 +29,25 @@ > Cubbyhole + + > + Databases (Beta) + + + > Generic @@ -36,16 +55,16 @@ MongoDB > - MSSQL + MSSQL (Deprecated) > - MySQL + MySQL (Deprecated) > PKI > - PostgreSQL + PostgreSQL (Deprecated) > RabbitMQ