github/vim-ale
1
0
Fork 0
mirror of https://github.com/webinstall/webi-installers.git synced 2026-02-14 17:49:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc(postgres): revamp with current best-known practices, separate server and client info

Browse Source
This commit is contained in:
AJ ONeal
2024-10-12 02:21:58 +00:00
parent 6924baca2b
commit d8fffe0dc3
1 changed files with 220 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files

290
postgres/README.md
View File

@@ -17,6 +17,11 @@ install:
~/.config/envman/PATH.env
~/.local/opt/postgres/
~/.local/share/postgres/var/postgresql.conf
# for psql (postgres client)
~/.pgpass
~/.psqlrc
~/.config/psql/
```
## Cheat Sheet
@@ -25,116 +30,261 @@ install:
> handles SQL, 'NoSQL', JSON, HSTORE, Full-Text Search, Messages Queues and
> more. Best bang for buck.
### Start the postgres server
Run just once (for development):
```sh
postgres -D $HOME/.local/share/postgres/var -p 5432
```
Run as a system service on Linux:
To enable Postgres as a Linux Service with [serviceman](../serviceman/): \
(see macOS below)
```sh
sudo env PATH="$PATH" \
serviceman add --system --username "$(whoami)" --name postgres -- \
postgres -D "$HOME/.local/share/postgres/var" -p 5432
serviceman add --system --username "$(whoami)" --name 'postgres' -- \
postgres -D ~/.local/share/postgres/var -p 5432
# Restart the logging service
sudo systemctl restart systemd-journald
```
### Connect with the psql client
To login: \
(see creating remote app users below)
```sh
psql 'postgres://postgres:postgres@localhost:5432/postgres'
# as Postgres admin
psql "postgres://postgres:postgres@localhost:5432/postgres"
# as remote user
psql "postgres://db-xxxx@pg-1.example.com:5432/db-xxxx?sslmode=require&sslnegotiation=direct"
```
### Initialize a database with a password
## Table of Contents
```sh
echo "postgres" > /tmp/pwfile
mkdir -p $HOME/.local/share/postgres/var/
- Server vs Client & PG Essentials
- Initialize a database with a password
- Start the Postgres Server
- development
- systemd (most Linuxes)
- OpenRC (container Linuxes)
- macOS
- Enable Secure Remote Access
- Create Secure Remote App (User/DB)
- Change an User's (App's) password
initdb -D $HOME/.local/share/postgres/var/ \
--username postgres --pwfile "/tmp/pwfile" \
--auth-local=password --auth-host=password
### Where to Find the Postgres Client Cheat Sheet
rm /tmp/pwfile
```
This is exclusively a server-side cheat sheet.
### Add and secure remote users
For the client-side cheat sheet, see [The PSQL (Client) Cheat Sheet](../psql/).
1. Set your server name or IP address
For a collection of other helpful scripts, see
[PG Essentials](https://github.com/bnnanet/pg-essentials):
- pg-register-service
- pg-addgroup
- pg-adduser
- pg-passwd
### How to Initialize the Postgres Database (with password)
1. Create a database directory, paired to the Postgres version
```sh
PG_HOST=pg-1.example.com
mkdir -p ~/.local/share/postgres-17/var/
```
2. Generate a 10-year self-signed TLS certificate
2. Use a password file and `initdb` to create a new DB directory
```sh
echo 'postgres' > /tmp/pwfile && \
initdb -D ~/.local/share/postgres/var/ \
--username 'postgres' --pwfile /tmp/pwfile \
--auth-local=password --auth-host=password \ &&
rm /tmp/pwfile
```
3. Test that the server starts
```sh
postgres -D ~/.local/share/postgres/var -p 5432
```
(kill with `ctrl+c`)
### How to run the Postgres server (daemon or foreground)
- foreground (development)
- systemd (Debian, Ubuntu, Redhat, etc)
- OpenRC (Alpine, Arch, Gentoo, etc)
- macOS (launchd)
#### To run in the foreground (for development):
```sh
postgres -D ~/.local/share/postgres/var -p 5432
```
#### Debian / Systemd
```sh
curl https://webi.sh/serviceman | sh
```
```sh
sudo env PATH="$PATH" \
serviceman add --system --username "$(whoami)" --name 'postgres' -- \
postgres -D ~/.local/share/postgres/var -p 5432
sudo systemctl restart systemd-journald
sudo journalctl -xefu postgres
```
#### Alpine / OpenRC
`/etc/init.d/postgres`:
```sh
#!/sbin/openrc-run
name="postgres"
description="postgres daemon"
command="/home/app/.local/opt/postgres/bin/postgres"
command_args="-D /home/app/.local/share/postgres/var -p 5432"
command_user="app:app"
supervisor="supervise-daemon"
output_log="/var/log/postgres"
error_log="/var/log/postgres"
depend() {
need net
}
start_pre() {
checkpath --directory --owner root /var/log/
checkpath --file --owner ${command_user} ${output_log} ${error_log}
}
start() {
ebegin "Starting ${name}"
supervise-daemon ${name} --start \
--stdout ${output_log} \
--stderr ${error_log} \
--pidfile /run/${RC_SVCNAME}.pid \
--respawn-delay 5 \
--respawn-max 10 \
-- \
${command} \
${command_args} \
eend $?
}
stop() {
ebegin "Stopping ${name}"
supervise-daemon ${name} --stop \
--pidfile /run/${RC_SVCNAME}.pid
eend $?
}
```
```sh
sudo rc-update add postgres
sudo rc-service postgres restart
sudo tail -f /var/log/postgres
```
#### macOS
```sh
serviceman add --name 'postgres' -- \
postgres -D ~/.local/share/postgres/var -p 5432
tail -f ~/.local/share/postgres/var/log/postgres.log
```
### How to Enable Secure Remote Postgres Access
1. Create the `my_remote_users` group:
```sh
echo 'CREATE ROLE "my_remote_users" NOLOGIN;' |
psql "postgres://postgres:postgres@localhost:5432/postgres" -f -
```
2. Update the hba permissions to enable App users (`sameuser`): \
`~/.local/share/postgres/var/pg_hba.conf`:
```ini
# Allow 'my_remote_users' to connect remotely directly over the internet
hostssl sameuser +my_remote_users 0.0.0.0/0 scram-sha-256
hostssl sameuser +my_remote_users ::0/0 scram-sha-256
# Allow 'my_remote_users' group to connect through a local TLS-terminating proxy
hostnossl sameuser +my_remote_users 127.0.0.1/8 scram-sha-256
hostnossl sameuser +my_remote_users ::1/128 scram-sha-256
host sameuser +my_remote_users 10.0.0.0/8 scram-sha-256
host sameuser +my_remote_users 172.16.0.0/12 scram-sha-256
host sameuser +my_remote_users 192.168.0.0/16 scram-sha-256
host sameuser +my_remote_users fc00::/7 scram-sha-256
```
3. Create a 10-year Self-signed cert for your server name or IP
```sh
my_host=pg-1.example.com
openssl req -new -x509 -days 3650 -nodes -text \
-out server.crt \
-keyout server.key \
-subj "/CN=$PG_HOST"
-out ./server.crt -keyout ./server.key -subj "/CN=$my_host"
chmod og-rwx server.key server.crt
mv server.key server.crt ~/.local/share/postgres/var/
chmod 0600 ./server.key ./server.crt
mv ./server.key ./server.crt ~/.local/share/postgres/var/
```
3. Enable SSL (TLS)
```sh
vim ~/.local/share/postgres/var/postgresql.conf
```
4. Update the main postgres config to allow secure connections: \
`~/.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
5. Restart Postgres for the change to take effect
```sh
MY_USER='my_user'
MY_PASSWORD="$(xxd -l16 -ps /dev/urandom)"
# all unixes
killall postgres
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
```sh
echo "$MY_PASSWORD"
```
6. Allow the user to connect via IPv4 and IPv6
```sh
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
```sh
# systemd (Debian, Ubunut, RedHat, Suse, etc)
sudo systemctl restart postgres
```
8. Test the connection from a remote system
```sh
PG_HOST="pg-1.example.com"
PG_USER="my_user"
# openrc (Alpine, Gentoo, Arch)
rc-service postgres restart
psql "postgres://$PG_USER@$PG_HOST/postgres?sslmode=require" << EOF
SELECT CURRENT_USER;
EOF
# macos
launchctl unload ~/Library/LaunchAgents/postgres.plist
launchctl load ~/Library/LaunchAgents/postgres.plist
```
(you will be prompted for your password / token)
### How to Create Secure Remote Users
### Add or update a user's password
The `sameuser` database directive REQUIRES the user and db name to be the same.
```sh
MY_USER='my_user'
MY_NEW_PASSWORD="$(xxd -l16 -ps /dev/urandom)"
my_app="foobar_xxxx"
# Update existing user with new password using new hash
echo "ALTER USER \"$MY_USER\" PASSWORD '$MY_NEW_PASSWORD';" |
# e.g. generate password / token with 'xxd -l16 -ps /dev/urandom'
my_token="db-token-for-the-app"
echo "
CREATE DATABASE \"$my_app\";
CREATE ROLE \"$my_app\" LOGIN INHERIT
IN ROLE \"my_remote_users\" ENCRYPTED PASSWORD '$my_token';
GRANT ALL PRIVILEGES ON DATABASE \"$my_app\" to \"$my_app\";
" | psql "postgres://postgres:postgres@localhost:5432/postgres" -f -
```
Notes:
- quote style matters:
- double quotes `"` for identifiers (users, tables, groups, roles)
- single quotes `'` for values (password)
### How to Change a DB's Password
```sh
my_app='foobar_xxxx'
my_token="$(xxd -l16 -ps /dev/urandom)"
echo "ALTER USER \"$my_app\" PASSWORD '$my_token';" |
psql 'postgres://postgres:postgres@localhost:5432/postgres' -f -
```