Self-Hosted MySQL

Create Certificate/Key Pair

Teleport uses mutual TLS authentication with self-hosted databases. As such, they must be configured with Teleport's certificate authority to be able to verify client certificates and a certificate/key pair that Teleport can verify.

Create the secrets:

Export Teleport's certificate authority and generate certificate/key pair
for host db.example.com with a 3-month validity period.
tctl auth sign --format=db --host=db.example.com --out=server --ttl=2190h

The command will create 3 files: server.cas, server.crt and server.key which you'll need to enable mutual TLS on your MySQL server.

Configure MySQL Server

To configure MySQL server to accept TLS connections, add the following to MySQL configuration file mysql.cnf:

[mysqld]
require_secure_transport=ON
ssl-ca=/path/to/server.cas
ssl-cert=/path/to/server.crt
ssl-key=/path/to/server.key

Additionally, MySQL database user accounts must be configured to require a valid client certificate:

CREATE USER 'alice'@'%' REQUIRE X509;
ALTER USER 'alice'@'%' REQUIRE X509;

By default the created user may not have access to anything and won't be able to connect so let's grant it some permissions:

GRANT ALL ON `%`.* TO 'alice'@'%';

See Configuring MySQL to Use Encrypted Connections in MySQL documentation for more details.

Setup Teleport Auth and Proxy Services

Teleport Database Access for MySQL is available starting from 6.0 release.

Download the latest version of Teleport for your platform from our downloads page and follow the installation instructions.

Teleport requires a valid TLS certificate to operate and can fetch one automatically using Let's Encrypt ACME protocol. We will assume that you have configured DNS records for teleport.example.com and *.teleport.example.com to point to the Teleport node.

Generate Teleport config with ACME enabled:

$ teleport configure --cluster-name=teleport.example.com --acme [email protected] -o file

Start Teleport Auth and Proxy services:

$ sudo teleport start

Database service requires a valid auth token to connect to the cluster. Generate one and save it in /tmp/token:

$ tctl tokens add --type=db

Create Role and User

Create the role that will allow a user to connect to any database using any database account:

tctl --config=/path/to/teleport-db-role.yaml create <<EOF
kind: role
version: v4
metadata:
  name: db
spec:
  allow:
    db_labels:
      '*': '*'
    db_names:
    - '*'
    db_users:
    - '*'
EOF

Create the user assigned the db role we've just created:

tctl --config=/path/to/teleport-db-role.yaml users add --roles=admin,db testuser

Start Database Service with CLI Flags

For a quick try-out, Teleport database service doesn't require a configuration file and can be launched using a single CLI command:

teleport db start \   --token=/tmp/token \   --auth-server=teleport.example.com:3080 \   --name=test \   --protocol=mysql \   --uri=mysql.example.com:3306 \   --labels=env=dev

Note that the --auth-server flag must point to the Teleport cluster's proxy endpoint because database service always connects back to the cluster over a reverse tunnel.

Start Database Service with Config File

Below is an example of a database service configuration file that proxies a single self-hosted MySQL database:

teleport:
  # The data_dir should be a different location if running on the same
  # machine as Teleport auth and proxy.
  data_dir: /var/lib/teleport-db
  nodename: teleport-db-instance
  # Teleport invitation token used to join a cluster.
  # can also be passed on start using --token flag
  auth_token: /tmp/token
  # Proxy address to connect to. Note that it has to be the proxy address
  # because database service always connects to the cluster over reverse
  # tunnel.
  auth_servers:
  - teleport.example.com:3080
db_service:
  enabled: "yes"
  # This section contains definitions of all databases proxied by this
  # service, can contain multiple items.
  databases:
    # Name of the database proxy instance, used to reference in CLI.
  - name: "example"
    # Free-form description of the database proxy instance.
    description: "Example MySQL"
    # Database protocol.
    protocol: "mysql"
    # Database address, MySQL server endpoint in this case.
    #
    # Note: this URI's hostname must match the host name specified via --host
    # flag to tctl auth sign command.
    uri: "mysql.example.com:3306"
    # Labels to assign to the database, used in RBAC.
    static_labels:
      env: dev
auth_service:
  enabled: "no"
ssh_service:
  enabled: "no"
proxy_service:
  enabled: "no"

Start the database service:

teleport start --config=/path/to/teleport-db.yaml --token=/tmp/token

Connect

Once the database service has joined the cluster, login to see the available databases:

tsh login --proxy=teleport.example.com --user=testuser
tsh db ls
Name    Description   Labels
------- ------------- --------
example Example MySQL env=dev

Note that you will only be able to see databases your role has access to. See RBAC section for more details.

To connect to a particular database server, first retrieve credentials from Teleport using tsh db login command:

tsh db login example

You can optionally specify the database name and the user to use by default when connecting to the database instance:

tsh db login --db-user=root --db-name=mysql example

Once logged in, connect to the database:

tsh db connect example

If you would like to see the native mysql shell connect command, run:

tsh db config --format=cmd example

To log out of the database and remove credentials:

Remove credentials for a particular database instance.
tsh db logout example
Remove credentials for all database instances.
tsh db logout