Add database documentation

This commit is contained in:
max furman 2019-04-25 18:27:11 -07:00
parent d72e076ca6
commit c8fe1ad86d
2 changed files with 110 additions and 1 deletions

View file

@ -102,9 +102,23 @@ and respond to requests.
* `dnsNames`: comma separated list of DNS Name(s) for the CA.
* `logger`: the default logging format for the CA is `text`. The other options
* `logger`: the default logging format for the CA is `text`. The other option
is `json`.
* `db`: data persistence layer. See [database documentation](./db.md) for more
info.
- type: `badger`, `bbolt`, `mysql`, etc.
- dataSource: `string` that can be interpreted differently depending on the
type of the database. Usually a path to where the data is stored. See
the [database configuration docs](./db.md#configuration) for more info.
- database: name of the database. Used for backends that may have
multiple databases. e.g. MySQL
- valueDir: directory to store the value log in (Badger specific).
* `tls`: settings for negotiating communication with the CA; includes acceptable
ciphersuites, min/max TLS version, etc.

95
docs/database.md Normal file
View file

@ -0,0 +1,95 @@
# Step Certificates Database
`step certificates` uses a simple key-value interface over popular database
implementations to store persistent certificate management meta-data.
Our recommended default database implementation is
[nosql-Badger](https://github.com/smallstep/nosql/badger) - a NoSQL interface
over the popular [Badger](https://github.com/dgraph-io/badger) database.
## What will the database store?
As a first pass, the database layer will store every certificate (along with
metadata surrounding the provisioning of the certificate) and revocation data
that will be used to enforce passive revocation.
## Implementations
Current implementations include Badger (default), BoltDB, and MysQL.
- [ ] Memory
- [x] [BoltDB](https://github.com/etcd-io/bbolt) -- etcd fork.
- [x] [Badger](https://github.com/dgraph-io/badger)
- [x] [MariaDB/MySQL](https://github.com/go-sql-driver/mysql)
- [ ] PostgreSQL
- [ ] Cassandra
- [ ] ...
Let us know which integration you would like to see next by opening an issue or PR.
## Configuration
Configuring `step certificates` to use a database is as simple as adding a
top-level `db` stanza to your `step-ca.config` (see getting started doc for
more info). Below are a few examples for supported databases:
### Badger
```
{
...
"crt": ".step/certs/intermediate_ca.crt",
"key": ".step/secrets/intermediate_ca_key",
"db": {
"type": "badger",
"dataSource": "./stepdb",
"valueDir": "./steplogdb" # leave empty if equivalent to dataSource
},
...
},
```
### BoltDB
```
{
...
"crt": ".step/certs/intermediate_ca.crt",
"key": ".step/secrets/intermediate_ca_key",
"db": {
"type": "bbolt",
"dataSource": "./stepdb"
},
...
},
```
### MySQL
```
{
...
"crt": ".step/certs/intermediate_ca.crt",
"key": ".step/secrets/intermediate_ca_key",
"db": {
"type": "mysql",
"dataSource": "user:password@tcp(127.0.0.1:3306)/",
"database": "myDatabaseName"
},
...
},
```
## Schema
As the interface is a key-value store, the schema is very simple. We support
`tables`, `keys`, and `values`. An entry in the database is a `[]byte value`
that is indexed by `[]byte table` and `[]byte key`.
## Data Backup
Backing up your data is important, and it's good hygiene. We chose
[Badger](https://github.com/dgraph-io/badger) as our default file based data
storage backend because it has mature tooling for running common database
tasks. See the [documentation](https://github.com/dgraph-io/badger#database-backup)
for a guide on backing up your data.