From fed138703744a678b75ff040e5260a5c2f810a4b Mon Sep 17 00:00:00 2001
From: AJ ONeal <aj@therootcompany.com>
Date: Wed, 3 Aug 2022 13:19:01 -0600
Subject: [PATCH] doc(postgres): add secure remote user instructions

---
 postgres/README.md | 81 +++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 80 insertions(+), 1 deletion(-)

diff --git a/postgres/README.md b/postgres/README.md
index 453237c..5c06d22 100644
--- a/postgres/README.md
+++ b/postgres/README.md
@@ -26,8 +26,11 @@ Run as a system service on Linux:
 
 ```bash
 sudo env PATH="$PATH" \
-    serviceman add --system --username $(whoami) --name postgres -- \
+    serviceman add --system --username "$(whoami)" --name postgres -- \
     postgres -D "$HOME/.local/share/postgres/var" -p 5432
+
+# Restart the logging service
+sudo systemctl restart systemd-journald
 ```
 
 ### Connect with the psql client
@@ -48,3 +51,79 @@ initdb -D $HOME/.local/share/postgres/var/ \
 
 rm /tmp/pwfile
 ```
+
+### Add and secure remote users
+
+1. Set your server name or IP address
+   ```bash
+   PG_HOST=pg-1.example.com
+   ```
+2. Generate a 10-year self-signed TLS certificate
+
+   ```bash
+   openssl req -new -x509 -days 3650 -nodes -text \
+       -out server.crt \
+       -keyout server.key \
+       -subj "/CN=$PG_HOST"
+
+   chmod og-rwx server.key server.crt
+   mv server.key server.crt ~/.local/share/postgres/var/
+   ```
+
+3. Enable SSL (TLS)
+   ```bash
+   vim ~/.local/share/postgres/var/postgresql.conf
+   ```
+   ```ini
+   ssl = on
+   password_encryption = scram-sha-256
+   listen_addresses = '*'
+   ```
+4. Generate a user with a random token password
+
+   ```bash
+   MY_USER='my_user'
+   MY_PASSWORD="$(xxd -l16 -ps /dev/urandom)"
+
+   echo "CREATE ROLE \"$MY_USER\" LOGIN ENCRYPTED PASSWORD '$MY_PASSWORD';" |
+       psql 'postgres://postgres:postgres@localhost:5432/postgres' -f -
+   ```
+
+5. Show the token password and save it somewhere
+   ```bash
+   echo "$MY_PASSWORD"
+   ```
+6. Allow the user to connect via IPv4 and IPv6
+   ```bash
+   echo "# Allow $MY_USER to connect remotely over the internet
+   hostssl all             $MY_USER        0.0.0.0/0               scram-sha-256
+   hostssl all             $MY_USER        ::0/0                   scram-sha-256" \
+       >> ~/.local/share/postgres/var/pg_hba.conf
+   ```
+7. Restart postgres
+   ```bash
+   sudo systemctl restart postgres
+   ```
+8. Test the connection from a remote system
+
+   ```bash
+   PG_HOST="pg-1.example.com"
+   PG_USER="my_user"
+
+   psql "postgres://$PG_USER@$PG_HOST/postgres?sslmode=require" << EOF
+   SELECT CURRENT_USER;
+   EOF
+   ```
+
+   (you will be prompted for your password / token)
+
+### Add or update a user's password
+
+```bash
+MY_USER='my_user'
+MY_NEW_PASSWORD="$(xxd -l16 -ps /dev/urandom)"
+
+# Update existing user with new password using new hash
+echo "ALTER USER \"$MY_USER\" PASSWORD '$MY_NEW_PASSWORD';" |
+    psql 'postgres://postgres:postgres@localhost:5432/postgres' -f -
+```