Versioning

How Zentinel versions work, mapping between release and crate versions, and changelogs.

Dual Versioning Scheme

Zentinel uses two versioning systems for different audiences:

SystemFormatExampleAudienceUsed For
Release VersionCalVer (YY.MM_PATCH)26.01_0Operators, enterprise, docsDownloads, release tags, LTS windows, support contracts
Crate VersionSemVer (MAJOR.MINOR.PATCH)0.3.0Library consumersCargo.toml, crates.io, dependency management

CalVer is the primary version. When you deploy Zentinel, report issues, reference documentation, or verify supply chain artifacts, use the CalVer release version. SemVer exists solely for Rust’s package ecosystem.

Release Version (CalVer)

All public-facing releases use Calendar Versioning in YY.MM_PATCH format:

YY.MM_PATCH

26.01_0  - January 2026, first release
26.01_1  - January 2026, first patch
26.02_0  - February 2026, first release
  • YY.MM identifies the release series (e.g., 26.01 = January 2026)
  • _PATCH increments for bug fixes and security patches within a series

This provides:

  • Age at a glance — 25.06_3 tells you the release is from June 2025
  • LTS windows tied to the calendar — an LTS branch like 26.01 LTS receives security backports for 12 months, through January 2027
  • Upgrade urgency — if you’re running 25.06_3 and the current release is 26.01_0, you’re 7 months behind

Crate Version (SemVer)

Rust crates published to crates.io use Semantic Versioning. This is an implementation detail for library consumers using Zentinel crates as dependencies. Operators do not need to track SemVer.

MAJOR.MINOR.PATCH

0.1.0  - Initial development
0.2.0  - New features (pre-1.0, may have breaking changes)
1.0.0  - First stable release
1.1.0  - New features, backwards compatible
1.1.1  - Bug fixes only
2.0.0  - Breaking changes

Which Version Do I Use?

ContextUse
Downloading binariesCalVer (26.01_0)
Docker image tagsCalVer (ghcr.io/zentinelproxy/zentinel:26.01_0)
Filing issues / support ticketsCalVer
Verifying supply chain signaturesCalVer (matches release tag)
LTS / support contractsCalVer series (26.01 LTS)
Cargo.toml dependenciesSemVer (zentinel = "0.3")
crates.ioSemVer

Version Mapping

This table maps CalVer release versions to their corresponding crate versions:

Release (CalVer)Crate Version (SemVer)ProtocolRelease DateStatus
26.03_10.5.120.2.02026-03-01Current
26.02_50.5.110.2.02026-02-27Previous
26.02_40.4.100.2.02026-02-04Previous
26.01_00.2.00.2.02026-01-01Previous
25.12_00.1.00.1.02025-12-15Archive
—0.1.00.1.02025-11-01Internal

Finding Your Version

From the binary:

zentinel --version
# zentinel 26.03_1 (0.5.12)

The CalVer release version is shown first, with the crate SemVer in parentheses.

From Docker:

docker inspect ghcr.io/zentinelproxy/zentinel:26.03_1 --format '{{ index .Config.Labels "org.opencontainers.image.version" }}'
# 26.03_1

From the documentation URL:

  • /docs/ — Current release (26.03)
  • /docs/v/26.02/ — Previous release
  • /docs/v/25.12/ — Archive

Changelogs

For the full changelog with all patch releases, see Changelog.

Release 26.03

Crate version: 0.5.12 Release date: March 2026

Changed

  • Image optimization agent v0.2.0 with Content-Type fix and improved defaults

Release 26.02

Crate version: 0.5.11 Release date: January – February 2026

Added

  • include directive in single-file config — include "routes/*.kdl" works directly in config files loaded via zentinel --config, with glob patterns, recursive expansion, and circular include detection
  • Supply chain security for release pipeline
    • SBOM generation in CycloneDX 1.5 and SPDX 2.3 formats
    • Binary signing with Sigstore cosign (keyless, GitHub Actions OIDC)
    • Container image signing with cosign and SBOM attestation
    • SLSA v1.0 provenance (Build Level 3)
  • Per-request allocation reduction in hot path
  • DNS-01 ACME challenge support for wildcard certificates
  • Agent Protocol v2 connection pooling, load balancing, reverse connections
  • Sticky load balancing algorithm
  • CI workflow (formatting, clippy, tests, docs checks)
  • Weekly cargo audit workflow with automatic issue creation
  • First-time user smoke tests (WAF, Lua)
  • protocol-version KDL config for agent blocks

Changed

  • Major dependency updates (opentelemetry, prost, tonic, tungstenite, sysinfo, reqwest, jsonschema, and more)
  • Pingora switched to raskell-io/pingora fork to remove protobuf vulnerability (RUSTSEC-2024-0437)

Fixed

  • Prevent single connection failure from permanently marking upstream target unhealthy
  • 16 rustdoc warnings across 10 files
  • Example configs now pass zentinel test validation

Release 26.01

Crate version: 0.2.0 – 0.3.0 Release date: January 2026

Added

  • Traffic Mirroring / Shadow Traffic

    • Fire-and-forget async request duplication to shadow upstreams
    • Percentage-based sampling (0-100%) for controlled traffic mirroring

  • API Schema Validation

    • JSON Schema validation for API routes (requests and responses)
    • OpenAPI 3.0 and Swagger 2.0 specification support

  • WebSocket frame inspection support in agent protocol

  • Graceful shutdown improvements

  • Connection draining during rolling updates

Changed

  • Improved upstream health check reliability
  • Reduced memory usage for idle connections

Security

  • Removed archived agents with unsafe FFI code (Lua, WAF, auth, denylist, ratelimit)
  • Replaced unreachable!() panics with proper error handling in agent-protocol

Release 25.12

Crate version: 0.2.0 Protocol version: 0.1.0 Release date: December 2025

Added

  • Core Proxy

    • HTTP/1.1 and HTTP/2 support
    • HTTPS with TLS 1.2/1.3
    • Configurable listeners (multiple ports, protocols)
    • Request/response header manipulation

  • Routing

    • Path-based routing with prefix, exact, and regex matching
    • Host-based virtual hosting
    • Method-based routing
    • Header-based routing conditions

  • Upstreams

    • Multiple backend targets with load balancing
    • Round-robin and random load balancing strategies
    • Active health checks (HTTP, TCP)
    • Passive health monitoring with circuit breaker
    • Connection pooling

  • Agent System

    • Unix socket transport for local agents
    • gRPC transport for remote agents
    • Request/response lifecycle hooks
    • WebSocket frame inspection hooks
    • Fail-open mode for agent failures
    • Agent timeout configuration

  • Observability

    • Prometheus metrics endpoint
    • Structured JSON logging
    • Request tracing with correlation IDs
    • OpenTelemetry integration

  • Configuration

    • KDL configuration format
    • Environment variable substitution
    • Configuration validation
    • Hot reload via SIGHUP

Upgrade Guides

From 26.01 to 26.02

No breaking changes. Direct upgrade supported.

# Stop current version
systemctl stop zentinel

# Install new version
VERSION="26.03_1"
curl -Lo /usr/local/bin/zentinel \
    "https://github.com/zentinelproxy/zentinel/releases/download/${VERSION}/zentinel-${VERSION}-linux-amd64.tar.gz"
tar -xzf "zentinel-${VERSION}-linux-amd64.tar.gz"
chmod +x zentinel && sudo mv zentinel /usr/local/bin/

# Validate configuration
zentinel validate -c /etc/zentinel/zentinel.kdl

# Start new version
systemctl start zentinel

New features to consider:

  • Supply Chain Security – verify binary and container authenticity
  • DNS-01 ACME challenges for wildcard certificates
  • Agent Protocol v2 connection pooling

From 25.12 to 26.01

No breaking changes. Direct upgrade supported.

New features to consider:

Compatibility Matrix

Agent Compatibility

Zentinel ReleaseProtocolCompatible Agent Versions
26.030.2.0Agents built with protocol 0.2.x
26.020.2.0Agents built with protocol 0.2.x
26.010.2.0Agents built with protocol 0.2.x
25.120.1.0Agents built with protocol 0.1.x

Rust Toolchain

Zentinel ReleaseMinimum Rust VersionRecommended
26.031.85.01.92.0+
26.021.85.01.85.0+
26.011.75.01.83.0+
25.121.70.01.75.0+

Release Schedule

Zentinel follows a monthly release cadence:

  • Feature releases: First week of each month (e.g., 26.02_0)
  • Patch releases: As needed for security or critical bugs (e.g., 26.01_1, 26.01_2)

Community Support

ReleaseStatusSecurity Fixes Until
26.03CurrentActive development
26.02Previous26.06 (3 months)
26.01Previous26.04 (3 months)
25.12EOLNo support

Community releases receive security patches for 3 months after the next release series ships.

Enterprise LTS

Enterprise customers receive long-term support branches designated by their CalVer series:

LTS BranchBased OnSecurity Fixes UntilConfig Stability
26.01 LTS26.01_0January 2027 (12 months)Guaranteed

LTS branches receive:

  • Security backports for 12 months from the initial release
  • Configuration compatibility — no breaking config changes within the LTS window
  • Patch releases on the same CalVer series (e.g., 26.01_1, 26.01_2, …)
  • Early security advisories before public disclosure

LTS is available through the Enterprise Builds offering. See Supply Chain Security for verification procedures.

See Also