open-vault/website/source/api/secret/databases/cassandra.html.md

147 lines
5.8 KiB
Markdown
Raw Normal View History

2017-05-03 09:13:07 +00:00
---
layout: "api"
page_title: "Cassandra - Database - Secrets Engines - HTTP API"
New Docs Website (#5535) * conversion stage 1 * correct image paths * add sidebar title to frontmatter * docs/concepts and docs/internals * configuration docs and multi-level nav corrections * commands docs, index file corrections, small item nav correction * secrets converted * auth * add enterprise and agent docs * add extra dividers * secret section, wip * correct sidebar nav title in front matter for apu section, start working on api items * auth and backend, a couple directory structure fixes * remove old docs * intro side nav converted * reset sidebar styles, add hashi-global-styles * basic styling for nav sidebar * folder collapse functionality * patch up border length on last list item * wip restructure for content component * taking middleman hacking to the extreme, but its working * small css fix * add new mega nav * fix a small mistake from the rebase * fix a content resolution issue with middleman * title a couple missing docs pages * update deps, remove temporary markup * community page * footer to layout, community page css adjustments * wip downloads page * deps updated, downloads page ready * fix community page * homepage progress * add components, adjust spacing * docs and api landing pages * a bunch of fixes, add docs and api landing pages * update deps, add deploy scripts * add readme note * update deploy command * overview page, index title * Update doc fields Note this still requires the link fields to be populated -- this is solely related to copy on the description fields * Update api_basic_categories.yml Updated API category descriptions. Like the document descriptions you'll still need to update the link headers to the proper target pages. * Add bottom hero, adjust CSS, responsive friendly * Add mega nav title * homepage adjustments, asset boosts * small fixes * docs page styling fixes * meganav title * some category link corrections * Update API categories page updated to reflect the second level headings for api categories * Update docs_detailed_categories.yml Updated to represent the existing docs structure * Update docs_detailed_categories.yml * docs page data fix, extra operator page remove * api data fix * fix makefile * update deps, add product subnav to docs and api landing pages * Rearrange non-hands-on guides to _docs_ Since there is no place for these on learn.hashicorp, we'll put them under _docs_. * WIP Redirects for guides to docs * content and component updates * font weight hotfix, redirects * fix guides and intro sidenavs * fix some redirects * small style tweaks * Redirects to learn and internally to docs * Remove redirect to `/vault` * Remove `.html` from destination on redirects * fix incorrect index redirect * final touchups * address feedback from michell for makefile and product downloads
2018-10-19 15:40:11 +00:00
sidebar_title: "Cassandra"
sidebar_current: "api-http-secret-databases-cassandra"
2017-05-03 09:13:07 +00:00
description: |-
The Cassandra plugin for Vault's database secrets engine generates database credentials to access Cassandra servers.
2017-05-03 09:13:07 +00:00
---
# Cassandra Database Plugin HTTP API
The Cassandra database plugin is one of the supported plugins for the database
secrets engine. This plugin generates database credentials dynamically based on
2017-05-03 09:13:07 +00:00
configured roles for the Cassandra database.
## Configure Connection
In addition to the parameters defined by the [Database
Secrets Engine](/api/secret/databases/index.html#configure-connection), this plugin
2017-05-03 09:13:07 +00:00
has a number of parameters to further configure a connection.
| Method | Path |
| :--------------------------- | :--------------------- |
| `POST` | `/database/config/:name` |
2017-05-03 09:13:07 +00:00
### Parameters
2017-05-03 09:13:07 +00:00
- `hosts` `(string: <required>)` Specifies a set of comma-delineated Cassandra
hosts to connect to.
- `port` `(int: 9042)` Specifies the default port to use if none is provided
as part of the host URI. Defaults to Cassandra's default transport port, 9042.
2017-05-03 09:13:07 +00:00
- `username` `(string: <required>)` Specifies the username to use for
superuser access.
- `password` `(string: <required>)` 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` secrets engine; see
2017-05-03 09:13:07 +00:00
[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.
- `local_datacenter` `(string: "")` If set, enables host selection policy
which will prioritize and use hosts which are in the local datacenter before
hosts in all other datacenters (for example "dc-01").
- `socket_keep_alive` `(string: "0s")` the keep-alive period for an active
network connection. If zero, keep-alives are not enabled.
- `consistency` `(string: "")`  Specifies the consistency option to use. See
the [gocql
definition](https://github.com/gocql/gocql/blob/master/frame.go#L188) for
valid options.
2017-05-03 09:13:07 +00:00
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 secrets engine.
2017-05-03 09:13:07 +00:00
### 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 \
2018-03-23 15:41:51 +00:00
http://127.0.0.1:8200/v1/cassandra/config/connection
2017-05-03 09:13:07 +00:00
```
## Statements
Statements are configured during role creation and are used by the plugin to
2018-03-20 18:54:10 +00:00
determine what is sent to the database on user creation, renewing, and
revocation. For more information on configuring roles see the [Role
API](/api/secret/databases/index.html#create-role) in the database secrets engine docs.
### Parameters
The following are the statements used by this plugin. If not mentioned in this
list the plugin does not support that statement type.
- `creation_statements` `(list: [])` 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 '{{username}}' and '{{password}}' values will be substituted. If not
provided, defaults to a generic create user statements that creates a
non-superuser.
- `revocation_statements` `(list: [])` 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 '{{username}}' value will be
substituted. If not provided defaults to a generic drop user statement.
- `rollback_statements` `(list: [])` Specifies the database statements to be
executed to rollback a create operation in the event of an error. 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 '{{username}}' value will be substituted. If not provided, defaults to
a generic drop user statement