From c24d06cc480b48fcc5ce5a805b2e3270bde76dfd Mon Sep 17 00:00:00 2001
From: Eugene <x@null.page>
Date: Wed, 20 Jul 2022 11:27:55 +0200
Subject: [PATCH] Created Adding a MySQL target (markdown)

---
 Adding-a-MySQL-target.md | 87 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 Adding-a-MySQL-target.md

diff --git a/Adding-a-MySQL-target.md b/Adding-a-MySQL-target.md
new file mode 100644
index 0000000..314d011
--- /dev/null
+++ b/Adding-a-MySQL-target.md
@@ -0,0 +1,87 @@
+This page explains the process of adding a new MySQL target host to Warpgate and allowing users to connect to it.
+
+> This feature is available in v0.4+
+
+# Authentication setup
+
+Currently, Wargate can connect to MySQL and MariaDB servers with a username/password via the `mysql_native_password` auth mode.
+
+As a MySQL protocol server, Warpgate only allows secure (TLS) connections and uses `mysql_clear_password` auth mode.
+
+# Enabling MySQL listener
+
+Enable the MySQL protocol in your config file (default: `/etc/warpgate.yaml`):
+
+```diff
++ mysql:
++   enable: true
++   certificate: /var/lib/warpgate/tls.certificate.pem
++   key: /var/lib/warpgate/tls.key.pem
+```
+
+You can reuse the same certificate and key that are used for the HTTP listener.
+
+# Connection setup
+
+Add the target host to the targets list in the Warpgate config file (default: `/etc/warpgate.yaml`), for example:
+
+```diff
+[...]
+  targets:
++   - name: db
++     allow_roles:
++       - "warpgate:admin"
++     mysql:
++       host: 192.168.1.10
++       port: 3306 # optional
++       username: dev
++       password: '123'
++       tls:
++         mode: preferred # or "disabled" or "required"
++         verify: false
+
+    - name: web-admin
+      allow_roles:
+        - "warpgate:admin"
+      web_admin: {}
+  users:
+[...]
+```
+
+Warpgate will automatically pick up any changes to the config file if it's valid, so give it a quick check:
+
+```
+$ warpgate check
+14:06:56  INFO Using config: "/etc/warpgate.yaml" (users: 1, targets: 2, roles: 1)
+14:06:56  INFO No problems found
+```
+
+The target should show up on the Warpgate homepage as well as on the _Targets_ admin UI page: 
+
+<img width="500" alt="image" src="https://user-images.githubusercontent.com/161476/179946932-e48c7128-c939-41e8-ab5d-9e3ad660ff87.png">
+
+Users will be able to click the entry to obtain connection instructions:
+
+<img width="500" alt="image" src="https://user-images.githubusercontent.com/161476/179947050-620f3ff3-887e-467c-974e-27efe428803d.png">
+
+# Client setup
+
+You can now use any MySQL/MariaDB client applications to connect through Warpgate with the following settings:
+
+* Host: the Warpgate host
+* Port: the Warpgate MySQL port (default: 33306)
+* Username: `admin#<target-name>` or `admin:<target-name>`, in this example: `admin#db`
+* Password: your Warpgate admin password
+* TLS: enabled
+* Cleartext password authentication: allowed
+
+If your client uses a database URL, use: `mysql://<username>#<target>:<password>@<warpgate host>:<warpgate mysql port>?sslMode=required`
+
+While your MySQL session is running, you'll be able to see its status in the Admin UI, including the query log: 
+
+<img width="500" alt="image" src="https://user-images.githubusercontent.com/161476/179948103-7d7f84f7-68a0-40c3-be1c-60892a7f0ace.png">
+
+
+# Up next
+
+* [[User authentication and roles]]
\ No newline at end of file