Skip to content

README.md

Latest commit

 

History

History
245 lines (169 loc) · 8.78 KB

README.md

File metadata and controls

245 lines (169 loc) · 8.78 KB
Raw

FreeBSD port for pgwd

This directory contains the FreeBSD port files for pgwd. Use them to build and install pgwd from the official ports tree (when accepted) or from a local port.

One config = one Postgres. For multiple instances (different clusters, thresholds), cron is often simpler: one cron entry per config file. See main README "Running from cron" and "Example: multiple services".

Supported architectures

The port sets ONLY_FOR_ARCHS= amd64 aarch64, aligned with prebuilt tarballs on each GitHub release:

  • pgwd_v<version>_freebsd_amd64.tar.gz
  • pgwd_v<version>_freebsd_arm64.tar.gz

FreeBSD uses aarch64 in ONLY_FOR_ARCHS; DISTFILES maps it to the arm64 suffix in the release filename (${ARCH:S/aarch64/arm64/}).

riscv64 is not listed until a pgwd_v*_freebsd_riscv64.tar.gz is published on releases and make install has been smoke-tested on FreeBSD riscv64. Do not add riscv64 to ONLY_FOR_ARCHS without both.

Install from port

When the port is in the official FreeBSD ports tree:

cd /usr/ports/sysutils/pgwd
make install

When using a local port (before it is accepted):

# Copy Makefile, pkg-plist, pkg-descr, rc.d/pgwd to ports/sysutils/pgwd/
cd ~/ports/sysutils/pgwd
make install

Reinstalling after updating port files: Run make deinstall, then make clean, then make install. Without make clean, the port may reuse a cached stage and not pick up changes (e.g. to rc.d/pgwd).

Verify install and handle upgrades

After make install (or make reinstall), verify the installed binary:

pgwd -version

If make install reports that an older package is already installed (for example pgwd-0.6.8), use:

make reinstall

This deinstalls the previous package and registers the new one cleanly.

Test with a local distfile (before a GitHub release)

The port normally fetches DISTFILES from MASTER_SITES (GitHub releases). To build or test install / plist against a tarball you built locally (no matching release on GitHub yet):

  1. Match the filename in DISTFILES for your architecture (e.g. pgwd_v1.0.1_freebsd_amd64.tar.gz when PORTVERSION= 1.0.1). From the pgwd repo root, **make port-freebsd-sync** updates **PORTVERSION** in this **Makefile** from the **VERSION` file.

    To generate that exact tarball layout/name locally (without running the full snapshot matrix), run from repo root:

    make dist-freebsd

    Output goes to dist/pgwd_v<version>_freebsd_<arch>.tar.gz using VERSION (for example dist/pgwd_v1.0.1_freebsd_amd64.tar.gz).

  2. Option A — copy into DISTDIR: From the port directory:

    cd ~/ports/sysutils/pgwd
distfile=$(make -V DISTFILES)   # expands PORTVERSION and ARCH
cp /path/to/pgwd/dist/"$distfile" "$(make -V DISTDIR)/"
make makesum    # refresh distinfo if checksums change
make install

  3. Option B — override MASTER_SITES for fetch: Put the tarball in a directory and point MASTER_SITES at a file: URL (absolute path, trailing slash):

    cd ~/ports/sysutils/pgwd
mkdir -p /tmp/pgwd-dist
cp /path/to/pgwd/dist/pgwd_v1.0.1_freebsd_amd64.tar.gz /tmp/pgwd-dist/
make makesum MASTER_SITES=file:///tmp/pgwd-dist/
make fetch MASTER_SITES=file:///tmp/pgwd-dist/
make install

    Use three slashes after file: for an absolute path (file:///tmp/...). Do not commit MASTER_SITES=file:... to the official ports tree; it is only for local validation.

The port installs:

  • Binary: /usr/local/bin/pgwd
  • Man page: /usr/local/share/man/man1/pgwd.1.gz
  • License: /usr/local/share/doc/pgwd/LICENSE
  • Config example: /usr/local/etc/pgwd/pgwd.conf.example
  • rc.d script: /usr/local/etc/rc.d/pgwd

Config (required)

pgwd reads /etc/pgwd/pgwd.conf by default. Copy the example and edit:

mkdir -p /etc/pgwd
cp /usr/local/etc/pgwd/pgwd.conf.example /etc/pgwd/pgwd.conf
vi /etc/pgwd/pgwd.conf   # client, databases[].url, notifications, etc.

Daemon (rc.d)

Setup

  1. Install the port and create the config (see Config above).
  2. Enable pgwd in rc.conf and start it:
echo 'pgwd_enable="YES"' >> /etc/rc.conf
service pgwd start

Commands

Command Action
service pgwd start Start the daemon
service pgwd stop Stop the daemon
service pgwd restart Restart the daemon
service pgwd status Check if running

To enable or disable on boot, edit /etc/rc.conf or /etc/rc.conf.local:

Setting Effect
pgwd_enable="YES" Start pgwd on boot
pgwd_enable="NO" Do not start pgwd on boot

rc.conf variables

Add these to /etc/rc.conf or /etc/rc.conf.local to customize the daemon:

Variable Default Description
pgwd_enable NO Set to YES to enable pgwd on boot
pgwd_flags -config /etc/pgwd/pgwd.conf CLI flags passed to pgwd (e.g. config path)
pgwd_config /etc/pgwd/pgwd.conf Config file path (used for required_files)
pgwd_env (none) Environment variables (e.g. KUBECONFIG=...)
pgwd_logfile /var/log/pgwd.log Log file for daemon output (stdout/stderr)

Example — default config path:

pgwd_enable="YES"
pgwd_flags="-config /etc/pgwd/pgwd.conf"

Example — custom config and kube-postgres:

pgwd_enable="YES"
pgwd_flags="-config /etc/pgwd/prod.conf"
pgwd_env="KUBECONFIG=/root/.kube/config"

When using -kube-postgres or -kube-loki, pgwd needs KUBECONFIG. Copy your kubeconfig to a path root can read (e.g. /root/.kube/config) and set pgwd_env.

Logging

The daemon writes to pgwd_logfile (default /var/log/pgwd.log). View logs with:

tail -f /var/log/pgwd.log

Log rotation: Add to /etc/newsyslog.conf:

/var/log/pgwd.log   644  5  100  *  B

Cron (one-shot)

For periodic checks instead of a daemon:

# crontab -e
PATH=/usr/local/bin:/usr/bin:/bin
*/5 * * * * pgwd -config /etc/pgwd/pgwd.conf >> /var/log/pgwd.log 2>&1

Log rotation: Add to /etc/newsyslog.conf:

/var/log/pgwd.log   644  5  100  *  B

Kubernetes (kube-postgres, kube-loki)

Use case: pgwd runs on an external FreeBSD host (e.g. VPS) with a kubeconfig that has access to the cluster. Postgres and Loki run inside the cluster. pgwd uses kubectl port-forward to reach both and sends alerts to Loki and Slack.

Install kubectl: pkg install kubectl.

Example config:

client: "pgwd-freebsd-01"
interval: 60
dry_run: false

# Deprecated: DISCOVER_MY_PASSWORD removed in 0.9.x — use Secret-backed password in URL
databases:
  - url: "postgres://postgres:YOUR_PASSWORD@localhost:25432/mydb"
    threshold:
      levels: "75,85,95"

kube:
  context: "my-context"
  local_port: 25432
  loki: "default/svc/loki"
  loki_local_port: 3100
  postgres: "default/svc/postgres"

notifications:
  loki:
    org_id: "my-tenant"
  slack:
    webhook: "https://hooks.slack.com/..."

Required: Set KUBECONFIG in the environment. For the rc.d daemon: pgwd_env="KUBECONFIG=/root/.kube/config" in rc.conf. For cron: KUBECONFIG=/root/.kube/config in the cron line or a wrapper script.

Grafana: Loki logs include a client label. Filter by {app="pgwd", client="pgwd-freebsd-01"}.

Port files

File Purpose
Makefile Port definition (fetch, extract, install)
pkg-plist List of files installed by the package
pkg-descr Package description (one line)
rc.d/pgwd rc.d script for daemon management

Submitting to official ports

When the port is ready, submit via Bugzilla (preferred) or see Porter's Handbook. The maintainer email in the Makefile must be valid and responsive.

Release and update procedure: See PORT-RELEASE.md for step-by-step instructions (version bump, makesum, gshar, Bugzilla). Run make port-freebsd-sync from the repo root to sync VERSION to the port before updating.