Rust edge gateway for websites, applications, caching, and load balancing.
Modular by design. Secure by default. Ready for rootless containers and regulated estates.

Home Page · Config Reference · Versioning Plan · Security

Fluxheim

Fluxheim is a modular Rust edge gateway for static sites, reverse proxying, edge caching, PHP-FPM application serving, ACME automation, observability, FIPS/ISO-capable TLS build paths, GeoIP policy, TCP stream proxying, and enterprise HTTP/TCP load balancing. The roadmap is moving Fluxheim-owned boundaries outward through standard HTTP/error types, native stream and load-balancer internals, explicit task orchestration, cache interfaces, server bootstrap, HTTP runtime ownership, and eventually HTTP/3/QUIC. The operator-facing product is Fluxheim: focused release profiles are available for full, cache, proxy, load-balancer, and PHP deployments, with matching container images and Linux runtime archives.

The 1.5.x load-balancer line targets F5 LTM, HAProxy, nginx, and Envoy-style HTTP/TCP pool operations: weighted and adaptive selection, health and circuit state, slow start, retry budgets, bounded queueing, local persistence, runtime member-state controls, status/metrics/audit visibility, and a validated enterprise migration fixture. It is not a complete BIG-IP platform clone: managed affinity cookies are local to one process, while a Fluxheim-native load-balancer core, restart-persistent load-balancer state, runtime add/remove-member, cross-instance state sync, UDP, GSLB, WAF, VPN/firewall appliance behavior, and iRules/Lua/Wasm scripting are documented future tracks rather than hidden or implied behavior. Runtime weight overrides are local, in-memory controls for round-robin and least-* selectors in the current 1.5.x line.

Fluxheim is licensed under the European Union Public Licence 1.2.

What Works Today

Serving And Routing

Capability	Status	Notes
Static websites	✅	MIME detection, index files, GET/HEAD, ETag, conditional 304, and single byte ranges.
Vhosts	✅	Host-header routing, default-vhost fallback, wildcard hosts, and opt-in strict host routing.
Route actions	✅	Static, proxy, redirect, and route-level policy blocks.
Regex path routing	✅	1.4.1; requires explicit global server.regex_enabled = true.
Regex capture variables	✅	1.4.1; bounded {route.regex.1} and {route.regex.name} variables for request headers and path-only rewrites.
Regex path rewrite templates	✅	1.4.1; rewrite_template maps regex routes to safe upstream paths without nginx-style rewrite loops or if.
Method-based routing	✅	1.4.1; optional route methods = ["GET", "HEAD"] filters.
HTTPS redirects	✅	Optional global HTTP-to-HTTPS redirects with safe Host validation.
Secure headers	✅	Request/response header policy, Server: fluxheim by default, removable by config.
PHP-FPM applications	✅	External php-fpm for existing pools.
Managed PHP-FPM	✅	Fluxheim-supervised php-fpm pools for zero-admin WordPress-style deployments.

Cache

Capability	Status	Notes
Proxy cache	✅	Vhost and route-scoped cache policies.
Memory cache	✅	Bounded in-memory cache tier.
Disk cache	✅	Filesystem and storage-bin disk backends.
Tiered cache	✅	Memory plus disk storage plans.
Encrypted disk cache	✅	Optional local-key and OpenBao transit encryption paths.
Static-file cache	✅	Optional local static-file caching.
Range and slice cache	✅	Bounded range caching and fixed-slice composition for large objects.
Peer fill	✅	Optional peer-assisted cache fill for cache-edge deployments.
Cache operations	✅	Hit/miss headers, cache locks, stale serving, cache warming, protected purge/status endpoints, and key/lookup diagnostics.

Proxy, TLS, And Edge Policy

Capability	Status	Notes
Reverse proxy	✅	Whole-vhost and route-level proxying.
Compression	✅	Optional gzip, Zstandard, and Brotli with vhost/route controls.
Load balancing	✅	Weighted round-robin, least/weighted/ratio least connections, least-sessions, least-time EWMA, priority groups, locality preference with fallback, per-upstream tags and in-flight caps, bounded queue/overflow policy, local source-IP/header/request-cookie persistence, signed/opaque managed affinity cookies, runtime persistence clear, weighted power-of-two, hash, consistent-hash, bounded-load consistent-hash, static-pool Maglev hash, backup, drain, disabled/forced-down members, runtime drain/disable/force-down/enable/manual-resume, runtime weight overrides for round-robin and least-* selectors, slow start, retry budgets/statuses, configurable all-down status, and a validated enterprise fixture in examples/load-balancer-enterprise.toml.
DNS-refreshed upstream pools	✅	1.4.1; upstream_dns_refresh_secs for load-balancer service-name pools.
File-refreshed upstream pools	✅	1.4.1; upstreams_file for load-balancer builds with bounded refresh and safe file handling.
Passive health	✅	Failure, selected 5xx, and latency-based ejection with circuit-open status visibility.
Active health checks	✅	TCP/TLS and HTTP health checks today; custom health request headers, gRPC health, JSON body validation, degraded weight signals, exec/agent checks, and database protocol probes are planned across later 1.5.x health-check lines.
Load-balancer status	✅	Admin status includes configured pools, selection/health/retry policy metadata, ready/available summary counts, runtime override counts/timestamps, backend readiness, disabled/drained state, in-flight counts, persistence-entry skew, passive failure/ejection and circuit state, slow-start, and least-time latency state.
Load-balancer 1.5.x boundaries	Limited	Local persistence and runtime overrides are in-memory only; managed affinity cookies and their rotating signing keys are process-local; Fluxheim does not yet persist LB state across restarts, add/remove members at runtime, apply runtime weights to hash/ring selectors, share managed-cookie keys, or sync state across active-active nodes.
Rate limits	✅	Local vhost/route token buckets, delay mode, bounded tables, and optional indeterminate-IP rejection.
Concurrency limits	✅	Vhost/route in-flight limits with bounded wait queues.
IP ACLs	✅	Trusted-proxy-aware allow/deny rules.
mTLS/client certificates	✅	Listener client-auth, fingerprint ACLs, and safe upstream identity forwarding templates.
TLS backends	✅	rustls default/recommended, plus OpenSSL for operators who need OpenSSL integration or OpenSSL FIPS provider deployments.
FIPS/ISO-capable builds	✅	OpenSSL FIPS provider path and rustls/AWS-LC FIPS-capable candidate path.
ACME	✅	Managed HTTP-01 and rustls TLS-ALPN-01 issuance/renewal, plus external HTTP-01 forwarding helper.
PROXY protocol	✅	v1/v2 receive and upstream send.
HTTP/2 origins	✅	Upstream HTTP version controls and bounded HTTP/2 settings.
gRPC pass-through	✅	Route-scoped HTTP/2 gRPC policy; no transcoding.
WebSocket / HTTP upgrade	✅	1.4.1; explicit proxy.websocket = true on HTTP/1.1 upstream routes.
External auth subrequests	✅	1.4.1; [proxy.auth_request] with bounded header/body forwarding.
Traffic mirroring	✅	1.4.1; traffic-mirror feature with safe bodyless shadow requests.
TCP stream proxying	✅	1.4.6+; optional stream-proxy feature with raw L4 TCP listeners, weighted upstream selection, drain/backup policy, bounded idle/lifetime/byte/connect controls, route-local PROXY protocol receive/send, and stream upstream TLS/mTLS controls.

Operations And Packaging

Capability	Status	Notes
Admin API	✅	Bearer-token auth, loopback defaults, brute-force throttling, authenticated health by default, snapshots, rollback, cache operations.
Read-only ops socket	✅	1.4.1; Unix-domain local status/cache/snapshot/health endpoint with owner/group-only permissions.
Prometheus metrics	✅	Native metrics profile and bounded labels for edge/cache/LB/PHP events.
OpenTelemetry	✅	OTLP metrics and tracing export profiles.
Structured access logs	✅	Trusted client IP, cache phase, route, selected upstream/alias/retries, TLS identity, compression, and optional Geo-Context fields.
Config tester	✅	Release-page config diagnostics through fluxheim-config-tester.
Rootless containers	✅	Wolfi, Alpine, SUSE Micro, Debian, focused full/cache/proxy/load-balancer/PHP images.
Native services	✅	systemd units and RPM packaging files.
Default page	✅	Packaged /srv/fluxheim/index.html with no external assets.

Planned Or Not Yet

Capability	Status	Target
Proxy module split	✅	1.4.2; access logs, compression, auth subrequests, traffic mirroring, edge policy, route policy, cache API DTOs, request-side cache policy, path safety, upstream TLS loading, PROXY protocol framing, and PHP-FPM process/spool/FastCGI handling are split into focused modules, with a new rule that future feature domains start outside the proxy orchestration file.
Config module split	✅	1.4.3; config loading, shared helpers, domain validation, and large config tests are split into focused config_* modules while keeping crate::config::* stable.
Load-balancer module split	✅	1.5.0; health checks, backend state, persistence, selection algorithms, backend policy/status, and file/DNS discovery are split into focused load_balancer/* modules while keeping crate::load_balancer::* stable.
Apple Silicon macOS dev builds	✅	1.4.4; Level 1 developer support with Mac-safe runtime paths while some upstream macOS support remains experimental.
GeoIP/Geo-Context policy	✅	1.4.5; optional geoip feature with local MMDB support for MaxMind GeoIP2/GeoLite2 and CIRCL Geo Open datasets, plus vhost/route country and ASN ACLs.
HTTP/3/QUIC	❌	Planned as a Fluxheim-owned 1.9 protocol milestone using the Rust quinn/h3 stack after server and HTTP runtime ownership are stable.
WASM policy hooks	❌	Planned for the later 1.6 extensibility line.

See Production Readiness for the precise stable-core promise and deployment checks. See macOS Development Support for the Level 1 Apple Silicon developer workflow.

Why Fluxheim

• Rust first: memory-safe implementation with a pinned stable toolchain.
• Production edge core: Fluxheim owns the config, security, operations, load-balancer, cache, PHP-FPM, stream, and observability model, with the remaining HTTP runtime internals being reduced behind project-owned boundaries over the 1.5 to 1.9 roadmap.
• Modular builds: compile only the modules needed for a deployment.
• Secure defaults: strict config validation, request limits, safe filesystem handling, dependency policy, and no hidden legacy protocol fallback.
• Container native: rootless-first examples and explicit runtime images for different operational policies.

Quick Start

Build the default development binary:

cargo build

Validate the local development config:

cargo run -- --check-config --config examples/fluxheim.toml

Run Fluxheim locally:

cargo run -- --config examples/fluxheim.toml

Then open http://127.0.0.1:8080 with a Host header that matches the default vhost, or use curl:

curl -H 'Host: localhost' http://127.0.0.1:8080/

Run the normal local checks:

scripts/checks.sh

Minimal Static Site Config

[server]
listen = ["0.0.0.0:8080"]
default_vhost = "site"

[headers.response]
enabled = true
x_content_type_options = "nosniff"
x_frame_options = "DENY"
referrer_policy = "no-referrer"

[[vhosts]]
name = "site"
hosts = ["example.test", "www.example.test"]

[vhosts.web]
root = "/srv/sites/example/public"
index_files = ["index.html"]
deny_dotfiles = true
cache_control = "public, max-age=60"

More examples live in examples. Native packages use packaging/default/fluxheim.toml, which listens on port 80 under the hardened systemd unit with CAP_NET_BIND_SERVICE; containers use packaging/container/fluxheim.toml, which keeps rootless-friendly internal ports 8080 and 8443. For the [[vhosts]] syntax and the recommended one-vhost-per-file layout, see Vhost Config Guide. For common multi-site proxy patterns, see Gateway Recipes.

Native/manual binary deployments can use the provided hardened systemd unit; see systemd Deployment.

Feature Builds

The default build is the recommended local/server baseline:

cargo build

It enables:

• proxy
• web
• cache
• tls-rustls
• security

Individual module features:

Feature	Default	Notes
proxy	Yes	Fluxheim reverse-proxy runtime; the current HTTP path is being isolated behind project-owned boundaries.
web	Yes	Static file resolver and static response handling. Runtime serving currently uses proxy sessions.
cache	Yes	Cache module compiled in; runtime cache remains disabled until configured.
load-balancer	No	Fluxheim load-balancing module, health checks, and runtime pool policy.
stream-proxy	No	Raw L4 TCP stream proxy service with separate stream semantics. Depends on the shared proxy runtime in 1.4.6; hardened in 1.4.7 with true idle timeouts, stream upstream TLS/mTLS controls, weighted/drain/backup policy, and expanded smoke coverage.
metrics	No	Prometheus metrics listener.
acme	No	ACME planning/renewal support. Requires TLS config and should be paired with one TLS backend for serving.
acme-client	No	Live ACME account/order HTTP client and background renewal service for HTTP-01 and rustls TLS-ALPN-01 certificate issuance and renewal.
php-fpm	No	PHP-FPM FastCGI bridge for WordPress-style PHP applications. Implies proxy and web; not included in default/focused images.
privacy-mode	No	Zero-retention static/proxy build profile.
security	Yes	Compile-time security profile marker plus release hardening checks. Runtime enforcement lives in the concrete config, TLS, filesystem, admin, and request-handling modules.
tls	No	Internal TLS marker used by TLS/ACME code; select a concrete backend for serving.
tls-rustls-fips	No	rustls/AWS-LC FIPS-capable TLS backend candidate for source builds.

For checked TLS policy examples, see examples/tls-modern.toml and examples/tls-intermediate.toml. For managed certificate issuance, see examples/acme-http-01.toml. For an issuer that requires External Account Binding, see examples/acme-actalis.toml. Packaged builds include acme-init for guided issuer bootstrap:

sudo fluxheim acme-init actalis
sudo fluxheim acme-init letsencrypt

Cargo does not provide a separate --group flag. Fluxheim uses normal Cargo feature aliases named profile-* for grouped builds.

Recommended profile features:

Profile feature	Enables	Use case
profile-core	proxy, web, cache, tls-rustls, security	Same intent as the default build.
profile-static-site	proxy, web, tls-rustls, security	Static sites without Fluxheim cache.
profile-reverse-proxy	proxy, tls-rustls, security	Reverse proxy without static hosting/cache.
profile-cache-server	proxy, web, cache, tls-rustls, security	Static/proxy server with cache enabled.
profile-load-balancer	proxy, web, cache, compression-gzip, compression-zstd, compression-brotli, load-balancer, tls-rustls, security	Edge server with Fluxheim load balancing and all compression codecs compiled in.
profile-observability	profile-core, metrics, metrics-otlp, otel-tracing, otel-otlp	Core server with Prometheus metrics, optional local OTLP metrics export, trace context propagation, and optional local OTLP trace export.
profile-privacy	proxy, web, tls-rustls, privacy-mode, security	Zero-retention static/proxy profile.
profile-full	profile-load-balancer, geoip, stream-proxy, traffic-mirror	All stable production modules, including GeoIP, traffic mirroring, and the 1.4 stream foundation.
profile-development	profile-full, php-fpm, acme-client, metrics, metrics-otlp, otel-tracing, otel-otlp	Broad development build with all compatible production modules.
profile-web-server	proxy, web, compression-gzip, compression-zstd, compression-brotli, tls-rustls, security	Static webserver profile while serving still uses the shared proxy runtime.
profile-cache-edge	proxy, cache, compression-gzip, compression-zstd, compression-brotli, tls-rustls, security	Cache edge without local static web serving.
profile-proxy-edge	proxy, compression-gzip, compression-zstd, compression-brotli, tls-rustls, security	Focused reverse proxy edge.
profile-load-balancer-edge	proxy, load-balancer, compression-gzip, compression-zstd, compression-brotli, tls-rustls, security	Load-balancer edge without cache or static web serving.
profile-fips-rustls	proxy, security, tls-rustls-fips	rustls/AWS-LC FIPS-capable candidate build.
profile-iso19790-rustls	profile-fips-rustls	ISO/IEC 19790 terminology alias for the same rustls/AWS-LC candidate path.

Fluxheim 1.3 started the focused image split. The profile-cache-edge and profile-proxy-edge aliases are TLS-capable without compiling local static web serving. Official RPMs, container images, and release tarballs add acme-client to the full, cache, and proxy profiles by default because managed certificates are the normal production path. Custom source builds can still omit acme-client for fully offline or static-certificate deployments. profile-cache-server and profile-load-balancer remain compatibility aliases for operators who want the older convenience bundles.

FIPS/ISO-capable OpenSSL testing is available with tls-openssl-fips, plus the tls-openssl-iso19790 terminology alias for ISO/IEC 19790-oriented evidence. Both require backend = "openssl" and an operator-installed OpenSSL 3 validated provider path. Use the profile-fips-openssl or profile-iso19790-openssl alias for local validation, run fluxheim crypto to inspect provider availability and OpenSSL default FIPS property status, and read FIPS / ISO-Capable Deployments before treating a deployment as regulated evidence.

The 1.3.5 release line added a rustls/AWS-LC candidate path with tls-rustls-fips, the ISO/IEC terminology alias tls-rustls-iso19790, profile-fips-rustls, and profile-iso19790-rustls. It builds aws-lc-fips-sys, so local validation requires CMake, Go, and a C compiler, plus the AWS-LC module certificate/Security Policy evidence for any regulated deployment.

Example grouped builds that match the official release artifacts:

cargo build --no-default-features --features profile-full,acme-client,metrics,metrics-otlp,otel-tracing,otel-otlp
cargo build --no-default-features --features profile-development
cargo build --no-default-features --features profile-cache-edge,acme-client
cargo build --no-default-features --features profile-proxy-edge,acme-client
cargo build --no-default-features --features profile-load-balancer-edge,acme-client
cargo build --no-default-features --features profile-web-server,php-fpm,acme-client

Official container images are published to GitHub Container Registry and Quay:

• ghcr.io/valkyoth/fluxheim
• quay.io/valkyoth/fluxheim

Release tags use the same profile/OS suffixes on both registries, for example v1.5.2-wolfi, v1.5.2-cache-wolfi, v1.5.2-proxy-wolfi, v1.5.2-load-balancer-wolfi, and v1.5.2-php-wolfi.

Manual feature selection also works:

cargo build --no-default-features --features proxy,web,tls-rustls,load-balancer

PHP support starts in 1.3.1 with an explicit php-fpm module. A PHP build can serve normal static assets from the same root while routing missing paths and explicit .php scripts to php-fpm. See docs/php-runtime-support.md, docs/php-fpm-app-recipes.md, and examples/php-fpm.toml. Fluxheim 1.3.7 completed the production PHP-FPM line with managed php-fpm supervision as an opt-in runtime mode. The Wolfi PHP image is self-contained for managed PHP-FPM and includes the Wolfi php-8.5-fpm runtime; non-Wolfi PHP image variants keep the external php-fpm container config unless customized. Pure-Rust PHP/phprs support is not planned; managed php-fpm is the supported zero-admin PHP path.

TLS backends are mutually exclusive. Select exactly one backend when TLS is needed:

TLS feature	Status
tls-rustls	Default and recommended.
tls-openssl	Optional OpenSSL backend.
tls-rustls-fips / tls-rustls-iso19790	rustls/AWS-LC FIPS-capable candidate backend.
tls-openssl-fips / tls-openssl-iso19790	OpenSSL FIPS provider backend.

Selecting more than one TLS backend is a compile error. Use scripts/validate-features.sh in packaging or custom CI jobs when accepting user-provided feature strings; Cargo features are additive, and Fluxheim supports one TLS backend per build.

Future optional modules such as waf, cloudflare, PHP, CGI, and legacy static HTTP are documented in the architecture docs but are not enabled in the default build.

Because cache is part of the default build, privacy builds must use --no-default-features through profile-privacy or an explicit manual feature set. Combining privacy-mode with cache or metrics fails at compile time.

Small manual builds:

cargo build --no-default-features --features proxy
cargo build --no-default-features --features proxy,web,tls-rustls
cargo build --no-default-features --features proxy,web,tls-rustls,privacy-mode

Validate a custom feature set before building:

scripts/validate-features.sh proxy,web,tls-rustls,load-balancer

Current Release: 1.5 Load Balancer

Fluxheim does not treat every planned idea as stable. The current release line is 1.5.x, starting with the 1.5.0 enterprise load-balancer/control-plane release.

• 1.0 is the gateway foundation: vhosts, routes, redirects, static serving, proxying, SNI/TLS, safe ACME challenge exceptions, systemd/RPM packaging, and rootless container operation.
• 1.1 is the certificate operations line: TLS policy profiles, multi-cert rustls SNI, managed ACME issuance/renewal, EAB-capable issuers, file-backed secrets, acme-init, and packaged renewal units.
• 1.2.x completed the production cache and observability line: vhost/route cache policy, memory/disk/tiered cache, local static-file caching, storage-bin disk cache, optional disk-cache encryption, peer fill, bounded range caching, fixed-slice range composition, cache operations tooling, Prometheus metrics, and OpenTelemetry export profiles.
• 1.3.x completed the split-profile and application-serving line: shared ingress/TLS feature profiles, focused full/cache/proxy/PHP images, the fluxheim-acme companion, release-page fluxheim-config-tester, production PHP-FPM support with WordPress-compatible front-controller behavior and Fluxheim-managed php-fpm supervision, OpenSSL and rustls/AWS-LC FIPS/ISO build paths, internal-crypto compliance guards, and the repeatable compliance evidence package template.
• 1.4.x completed the production proxy parity and platform-hardening line: edge ACLs, rate/concurrency limits, gzip/zstd/brotli compression, regex/template rewrites, method routing, WebSocket upgrades, auth subrequests, traffic mirroring, read-only ops socket, passive and active health checks, retry budgets, PROXY protocol v1/v2, upstream TLS controls, mTLS/client certificate policy, HTTP/2 origin controls, gRPC pass-through, Apple Silicon Level 1 development support, bounded GeoIP/Geo-Context policy, TCP stream proxying with idle timeouts and stream upstream TLS/mTLS, and the proxy/config module splits that keep future feature domains in focused files.
• 1.5.x is the enterprise load-balancer/control-plane line. It promotes the load-balancer image profile and focuses on F5/HAProxy/Envoy-class pool operations: runtime pool/member mutation, priority groups, persistence, slow-start, richer active/adaptive health checks, circuit breaking, queue and overflow behavior, locality/failure-domain policy, richer selection algorithms, admin/audit visibility, and migration fixtures. It is not a WAF, GSLB/DNS appliance, UDP proxy, or iRules-compatible scripting release. See Load Balancer Migration Notes for HAProxy, nginx, and F5 pool mappings.

Detailed cache behavior, config examples, operational limits, and smoke-test coverage are documented in Cache Backends, Cache Encryption, Config Reference, and Production Readiness.

Next lines are planned separately after 1.5: 1.6 for shared Wasm extensibility covering nginx-Lua-style hooks and VCL-like cache policy hooks, then later major dependency-reduction lines for Fluxheim-owned server bootstrap/listener/TLS handling, the HTTP proxy runtime, and HTTP/3/QUIC based on the Rust quinn/h3 stack. See Versioning Plan and Roadmap for the full release ladder.

Documentation

• Roadmap
• Changelog
• Versioning Plan
• Release Runbook
• Release Checklist
• Build, Containers, And Rootless Podman
• Production Readiness
• Feature Matrix
• OWASP Top 10 2025 Baseline
• FIPS-Capable Deployments
• Config Reference
• Load Balancer Migration Notes
• Gateway Recipes
• GitHub Repository Setup
• Cache Backends
• Cache Encryption
• Image Filter
• Programmable Media Edge
• Certificate Renewal And Reload
• Config Snapshots And Rollback
• Logging Architecture
• Metrics Architecture
• OpenTelemetry Tracing
• WASM Extensibility
• Crypto RPC Edge
• External Authorization Request
• Zero-Retention Privacy Mode
• WAF Architecture
• Rust Supply-Chain Security
• Cloudflare Origin Support
• PHP Runtime Support
• Perl CGI Support
• Legacy Static HTTP Support
• Sentinel Mesh

Security And Dependency Policy

Fluxheim uses:

• pinned Rust stable toolchain;
• checked-in Cargo.lock;
• GitHub CI and CodeQL scanning;
• cargo deny for license and dependency policy;
• cargo audit for advisory checks;
• SBOM and reproducible-build evidence for stable releases;
• scripts/validate-owasp-top10-2025.sh for a mapped OWASP Top 10 2025 baseline over Fluxheim-owned controls;
• rootless Podman smoke tests before container releases.

Before publishing or merging security-sensitive changes:

scripts/release_checks.sh

See SECURITY.md for vulnerability reporting and Rust Supply-Chain Security for dependency review policy.

License

Fluxheim is distributed under the European Union Public Licence v1.2.