1--- 2layout: "docs" 3page_title: "MySQL - Secrets Engines" 4sidebar_title: "MySQL <sup>DEPRECATED</sup>" 5sidebar_current: "docs-secrets-mysql" 6description: |- 7 The MySQL secrets engine for Vault generates database credentials to access MySQL. 8--- 9 10# MySQL Secrets Engine 11 12Name: `mysql` 13 14~> **Deprecation Note:** This secrets engine is deprecated in favor of the 15combined databases secrets engine added in v0.7.1. See the documentation for 16the new implementation of this secrets engine at 17[MySQL/MariaDB database plugin](/docs/secrets/databases/mysql-maria.html). 18 19The MySQL secrets engine for Vault generates database credentials 20dynamically based on configured roles. This means that services that need 21to access a database no longer need to hardcode credentials: they can request 22them from Vault, and use Vault's leasing mechanism to more easily roll keys. 23 24Additionally, it introduces a new ability: with every service accessing 25the database with unique credentials, it makes auditing much easier when 26questionable data access is discovered: you can track it down to the specific 27instance of a service based on the SQL username. 28 29Vault makes use of its own internal revocation system to ensure that users 30become invalid within a reasonable time of the lease expiring. 31 32This page will show a quick start for this secrets engine. For detailed documentation 33on every path, use `vault path-help` after mounting the secrets engine. 34 35## Quick Start 36 37The first step to using the mysql secrets engine is to mount it. Unlike the `kv` 38secrets engine, the `mysql` secrets engine is not mounted by default. 39 40``` 41$ vault secrets enable mysql 42Success! Enabled the mysql secrets engine at: mysql/ 43``` 44 45Next, we must configure Vault to know how to connect to the MySQL 46instance. This is done by providing a [DSN (Data Source Name)](https://github.com/go-sql-driver/mysql#dsn-data-source-name): 47 48``` 49$ vault write mysql/config/connection \ 50 connection_url="root:root@tcp(192.168.33.10:3306)/" 51Success! Data written to: mysql/config/connection 52``` 53 54In this case, we've configured Vault with the user "root" and password "root, 55connecting to an instance at "192.168.33.10" on port 3306. It is not necessary 56that Vault has the root user, but the user must have privileges to create 57other users, namely the `GRANT OPTION` privilege. 58 59For using UNIX socket use: `root:root@unix(/path/to/socket)/`. 60 61Optionally, we can configure the lease settings for credentials generated 62by Vault. This is done by writing to the `config/lease` key: 63 64``` 65$ vault write mysql/config/lease \ 66 lease=1h \ 67 lease_max=24h 68Success! Data written to: mysql/config/lease 69``` 70 71This restricts each credential to being valid or leased for 1 hour 72at a time, with a maximum use period of 24 hours. This forces an 73application to renew their credentials at least hourly, and to recycle 74them once per day. 75 76The next step is to configure a role. A role is a logical name that maps 77to a policy used to generate those credentials. For example, lets create 78a "readonly" role: 79 80``` 81$ vault write mysql/roles/readonly \ 82 sql="CREATE USER '{{name}}'@'%' IDENTIFIED BY '{{password}}';GRANT SELECT ON *.* TO '{{name}}'@'%';" 83Success! Data written to: mysql/roles/readonly 84``` 85 86By writing to the `roles/readonly` path we are defining the `readonly` role. 87This role will be created by evaluating the given `sql` statements. By 88default, the `{{name}}` and `{{password}}` fields will be populated by 89Vault with dynamically generated values. This SQL statement is creating 90the named user, and then granting it `SELECT` or read-only privileges 91to tables in the database. More complex `GRANT` queries can be used to 92customize the privileges of the role. See the [MySQL manual](https://dev.mysql.com/doc/refman/5.7/en/grant.html) 93for more information. 94 95To generate a new set of credentials, we simply read from that role: 96 97``` 98$ vault read mysql/creds/readonly 99Key Value 100--- ----- 101lease_id mysql/creds/readonly/bd404e98-0f35-b378-269a-b7770ef01897 102lease_duration 3600 103password 132ae3ef-5a64-7499-351e-bfe59f3a2a21 104username readonly-aefa635a-18 105``` 106 107By reading from the `creds/readonly` path, Vault has generated a new 108set of credentials using the `readonly` role configuration. Here we 109see the dynamically generated username and password, along with a one 110hour lease. 111 112Using ACLs, it is possible to restrict using the mysql secrets engine such 113that trusted operators can manage the role definitions, and both 114users and applications are restricted in the credentials they are 115allowed to read. 116 117Optionally, you may configure both the number of characters from the role name 118that are truncated to form the display name portion of the mysql username 119interpolated into the `{{name}}` field: the default is 10. 120 121You may also configure the total number of characters allowed in the entire 122generated username (the sum of the display name and uuid portions); the 123default is 16. Note that versions of MySQL prior to 5.8 have a 16 character 124total limit on user names, so it is probably not safe to increase this above 125the default on versions prior to that. 126 127## API 128 129The MySQL secrets engine has a full HTTP API. Please see the 130[MySQL secrets engine API](/api/secret/mysql/index.html) for more 131details. 132