hypershunt 1.1.0

Status: stable — 1.1.0. The configuration format is stable and the project follows semantic versioning.

hypershunt puts the whole serving stack in one coherent place: a modern KDL configuration instead of accreted directive syntax, first-class operations (systemd socket activation, hot config reload, seamless binary upgrades with zero dropped connections), and batteries-included authentication — OIDC single sign-on, JWT sessions, PAM/LDAP/htpasswd — with no separate auth proxy to deploy.

A static site and an API behind automatic TLS is this:

server state-dir="/var/lib/hypershunt"   // ACME certificate storage

listener "tcp://[::]:80"             // ACME challenges + redirects
listener "tcp://[::]:443" {
    tls "acme" email="you@example.com" {
        domain "example.com"
        domain "api.example.com"
    }
}

vhost "example.com" {
    location "/" { static root="/var/www/example" }
}

vhost "api.example.com" {
    location "/" { proxy { upstream "http://127.0.0.1:8080" } }
}

Or try it in one line, no root required — the container serves its own documentation out of the box:

podman run --rm --pull=newer -p 8080:80 -p 8443:443 ghcr.io/michaelpaddon/hypershunt:latest

Open http://localhost:8080 (or https://localhost:8443 with the ephemeral self-signed certificate), then walk through the Quick start.

Features

• Serving --- static files (range, ETag, try-files), redirects, inline responses, custom error pages.
• Routing --- virtual hosts (literal + regex), request matchers, URL rewrites with regex captures.
• Reverse proxy --- HTTP/1, HTTP/2, HTTP/3 upstreams; load balancing, health checks, retries; FastCGI, SCGI, CGI.
• Layer-4 proxy --- TCP, UDP, and Unix-socket forwarders with optional TLS termination.
• TLS --- ACME (HTTP-01, DNS-01, TLS-ALPN-01), file-based PEM, self-signed; OCSP stapling; mTLS with CRLs.
• Auth & access control --- HTTP Basic (PAM, LDAP, htpasswd), JWT sessions, OIDC SSO, firewall-style policy blocks.
• Operations --- compression, structured access logs, status page, health endpoints, hot reload, seamless binary upgrade, .deb / .rpm / OCI image.

…and more --- see the configuration reference.

Standards

Documentation

• Quick start --- five-minute container walkthrough.
• Configuration guide --- scenario-driven walkthroughs.
• Configuration reference --- every directive hypershunt accepts.
• Grammar --- formal KDL syntax.
• Manual --- the hypershunt(1) man page.

Install

Every release ships .deb and .rpm packages:

sudo dpkg -i hypershunt_<version>_<arch>.deb    # Debian/Ubuntu
sudo rpm -i  hypershunt-<version>.<arch>.rpm    # RHEL/Fedora
sudo systemctl enable --now hypershunt

Or install from source via crates.io:

cargo install hypershunt

This compiles from source and needs a C toolchain (cmake + a C compiler; PAM headers on Unix) for the native dependencies --- the prebuilt packages above are the lighter path.

Building from source (prerequisites, tests, and packaging) is covered in BUILD.md.

Next steps: the Quick start, then the configuration guide.

fail2ban

The .deb / .rpm packages install ready-to-use (disabled) fail2ban jails for the security signals. For the container image they're bundled at /usr/share/doc/hypershunt/fail2ban/ to copy onto the host — fail2ban runs on the host, not in the container.

Operations notes

A fresh install ships an empty /var/www/hypershunt/ and redirects / to the bundled docs at /docs/; drop your own index.html into the webroot and the redirect stops firing.

License

BSD 2-Clause --- see LICENSE.