Yabber

Project website · Downloads

Yabber is a small HTTP and HTTPS gateway for routers and home servers. It terminates TLS, matches requests by hostname and path, and forwards them to local services, Docker containers, static files, redirects or fixed responses, and obtains certificates automatically over ACME. It is built on net/http and httputil.ReverseProxy, and is meant to replace Caddy or nginx where all you need is "this domain goes to that port".

It is both a command and a Go library: the gateway can be embedded in another program and reconfigured at runtime through its API.

Install

curl -fsSL https://github.com/lsongdev/yabber/releases/latest/download/install.sh | sh

The installer picks the build for this machine, verifies it against the release's SHA256SUMS, and installs a service:

	Binary	Configuration	Data	Service
OpenWrt	/usr/bin/yabber	/etc/yabber/config.yaml	/etc/yabber	/etc/init.d/yabber, kept across sysupgrade
systemd	/usr/local/bin/yabber	/var/lib/yabber/config.yaml	/var/lib/yabber	yabber.service, user yabber, API on 127.0.0.1:9180

A first install writes a starter configuration and leaves the service stopped; running the installer again upgrades the binary and service files and restarts the service without touching the configuration. -v VERSION installs a specific release, -n only the binary, and YABBER_MIRROR points it at a mirror. The installer checks the release signature when openssl supports Ed25519 (opkg install openssl-util on OpenWrt) and refuses a mirror it cannot verify.

On OpenWrt, move LuCI off ports 80 and 443 first (the installer prints how). To serve the management panel on the LAN, set the address in /etc/config/yabber and restart:

uci set yabber.main.admin=192.168.1.1:9180 && uci commit yabber && /etc/init.d/yabber restart

Command

Download a binary from the releases (one per day, tagged with the date), or build it:

go install github.com/lsongdev/yabber/cmd/yabber@latest
make build            # dist/yabber for this machine
make -j dist          # every platform, plus SHA256SUMS

yabber run -d /var/lib/yabber -c /etc/yabber/config.yaml
yabber check -d /var/lib/yabber -c /etc/yabber/config.yaml
yabber reload -d /var/lib/yabber
yabber update            # or: yabber update -check
yabber version

run is the default command. Every command takes:

Flag	Meaning
-d DIR	data directory: state yabber writes (ACME accounts and certificates, yabber.pid)
-c FILE	configuration file, DIR/config.yaml by default

Without -d, the data directory is the configuration file's directory, so yabber -d /etc/yabber and yabber -c /etc/yabber/config.yaml are the same. Keeping the configuration in the data directory, as the installer does, lets the management API save changes; the systemd unit leaves /etc read-only to the service.

run also takes -admin 127.0.0.1:9180 (the management API, /metrics and /healthz), -access-log (JSON access logs on stdout) and -debug.

One instance per data directory. run holds an exclusive lock on DIR/yabber.pid, so two instances can never share ACME state; instances with different directories run side by side. reload signals the instance holding the lock, and a pid file left behind by a crash is recognized as stale. SIGHUP (systemctl reload, /etc/init.d/yabber reload) does the same: the configuration and certificates are reloaded without dropping connections, and an invalid file is logged while the running configuration stays. SIGINT and SIGTERM drain in-flight requests and exit.

Updates. update downloads the release build for this platform, verifies it against SHA256SUMS, runs it once, and atomically replaces the binary; restart the service afterwards. Builds on the same day share a date tag, so it compares checksums rather than versions.

Releases are signed: CI signs SHA256SUMS with an Ed25519 key (SHA256SUMS.sig) whose public half is compiled into yabber, and update refuses anything it cannot verify. That makes any mirror safe to use, such as a GitHub proxy where GitHub itself is slow or blocked:

yabber update -mirror https://ghfast.top/https://github.com/lsongdev/yabber/releases/latest/download
# or set YABBER_MIRROR, which install.sh honors too

A mirror is a URL of a directory holding one release's files.

Logs go to stderr. Yabber writes no log files of its own: journald and OpenWrt's logd already keep, rotate and cap them. Access logs are off by default; on OpenWrt, where logd is a small RAM ring, they would push out the system log. Important events (certificates issued or failing, ACME account changes, applied configurations, listener failures) are also kept in memory for Server.Events.

Inline JavaScript Worker handlers add about 10 MB to the binary and are opt-in: go build -tags worker ./cmd/yabber.

Automatic HTTPS

tls:
  acme:
    email: [email protected]

sites:
  - hosts: [app.example.com]
    proxy: http://127.0.0.1:3000

With tls.acme, every host served over TLS that no listed certificate covers gets its own certificate through ACME HTTP-01. Yabber listens on :80 and :443, registers an account (agreeing to the CA's terms), answers challenges ahead of the HTTP-to-HTTPS redirect, and renews each certificate two thirds into its lifetime. Failed attempts back off from 5 minutes to 12 hours; a reload (SIGHUP or Apply) retries failing hosts after at most a minute, so fixing DNS and reloading takes effect at once.

This is the beginning of the README. Read the rest at the original. Read the full README ↗