Skip to content

docs: ACME updates for 26.04 releases #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
raffaelschneider merged 1 commit into from
Apr 20, 2026
Merged

docs: ACME updates for 26.04 releases #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 91 additions & 6 deletions content/configuration/listeners.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -436,7 +436,7 @@ Connections in progress continue with old certificates. New connections use upda

## ACME (Automatic Certificate Management)

Zentinel supports automatic TLS certificate management using the ACME protocol (RFC 8555). This eliminates manual certificate management by automatically requesting, validating, and renewing certificates from Let's Encrypt.
Zentinel supports automatic TLS certificate management using the ACME protocol (RFC 8555). This eliminates manual certificate management by automatically requesting, validating, and renewing certificates from ACME-compatible CAs (Let's Encrypt, ZeroSSL, Step-ca, etc.).

### Basic ACME Configuration

Expand All @@ -454,9 +454,9 @@ listener "https" {
```

With ACME enabled, Zentinel will:
1. Create or restore a Let's Encrypt account
1. Create or restore an ACME account (Let's Encrypt by default, or a custom CA)
2. Request certificates for configured domains
3. Complete HTTP-01 domain validation automatically
3. Complete HTTP-01 or DNS-01 domain validation automatically
4. Store certificates securely on disk
5. Renew certificates before expiration
6. Hot-reload certificates without proxy restart
Expand All @@ -477,19 +477,32 @@ listener "https" {
staging #false // Use staging environment for testing
storage "/var/lib/zentinel/acme" // Certificate storage directory
renew-before-days 30 // Days before expiry to renew
key-type "ecdsa-p256" // Key type: ecdsa-p256, ecdsa-p384

// Custom ACME server (e.g., ZeroSSL, Step-ca)
// server-url "https://acme.zerossl.com/v2/DV90"

// External Account Binding (required by some CAs)
// eab {
// kid "your-eab-kid"
// hmac-key "your-base64url-encoded-hmac-key"
// }
}
}
}
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `email` | string | **required** | Contact email for Let's Encrypt account |
| `email` | string | **required** | Contact email for ACME account |
| `domains` | string[] | **required** | Domains to include in certificate |
| `staging` | bool | `false` | Use Let's Encrypt staging environment |
| `server-url` | string | - | Custom ACME directory URL (e.g., ZeroSSL, Step-ca) |
| `staging` | bool | `false` | Use Let's Encrypt staging environment (ignored if `server-url` is set) |
| `eab` | block | - | External Account Binding credentials (required by some CAs) |
| `storage` | path | `/var/lib/zentinel/acme` | Directory for certificates and credentials |
| `renew-before-days` | u32 | `30` | Days before expiry to trigger renewal |
| `challenge-type` | string | `"http-01"` | Challenge type: `http-01` or `dns-01` |
| `key-type` | string | `"ecdsa-p256"` | Certificate key type: `ecdsa-p256`, `ecdsa-p384` |
| `dns-provider` | block | - | DNS provider config (required for `dns-01`) |

### HTTP-01 Challenge (Default)
Expand Down Expand Up @@ -566,9 +579,31 @@ listener "https" {

| Provider | Type | Description |
|----------|------|-------------|
| Cloudflare | `cloudflare` | Cloudflare DNS API v4 |
| Hetzner | `hetzner` | Hetzner DNS API |
| Webhook | `webhook` | Generic webhook for custom integrations |

#### Cloudflare DNS Provider

```kdl
dns-provider {
type "cloudflare"
credentials-file "/etc/zentinel/secrets/cloudflare-token.txt"
api-timeout-secs 30

propagation {
initial-delay-secs 20
check-interval-secs 10
timeout-secs 300
nameservers "1.1.1.1" "8.8.8.8"
}
}
```

The token needs **Zone.DNS:Edit** and **Zone.Zone:Read** permissions. Credential file is plain text (the token itself) or JSON `{"token": "..."}`.

Zone IDs are resolved and cached automatically from the domain name.

#### Hetzner DNS Provider

```kdl
Expand Down Expand Up @@ -607,7 +642,7 @@ The webhook provider makes HTTP calls:

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `type` | string | **required** | Provider type: `hetzner`, `webhook` |
| `type` | string | **required** | Provider type: `cloudflare`, `hetzner`, `webhook` |
| `credentials-file` | path | - | Path to credentials JSON file |
| `credentials-env` | string | - | Environment variable with credentials |
| `api-timeout-secs` | u64 | `30` | API request timeout |
Expand Down Expand Up @@ -642,6 +677,56 @@ your-api-token

Security: Credential files should have mode `0600` or `0400`.

### Custom ACME Server and EAB

By default, Zentinel uses Let's Encrypt. To use a different ACME-compatible CA (ZeroSSL, BuyPass, Step-ca), set `server-url` to the CA's directory URL. Some CAs also require External Account Binding (EAB) credentials.

```kdl
tls {
acme {
email "admin@example.com"
domains "example.com" "www.example.com"

// Custom ACME directory URL
server-url "https://acme.zerossl.com/v2/DV90"

// EAB credentials (obtain from your CA's dashboard)
eab {
kid "your-eab-kid"
hmac-key "your-base64url-encoded-hmac-key"
}
}
}
```

| EAB Option | Type | Description |
|------------|------|-------------|
| `kid` | string | Key ID provided by the ACME CA |
| `hmac-key` | string | HMAC key (base64url-encoded) provided by the ACME CA |

When `server-url` is set, the `staging` option is ignored.

### Certificate Key Type

Zentinel allows configuring the key algorithm for ACME certificates:

```kdl
tls {
acme {
email "admin@example.com"
domains "example.com"
key-type "ecdsa-p384"
}
}
```

| Value | Description |
|-------|-------------|
| `ecdsa-p256` | ECDSA with NIST P-256 curve (default, fast and widely supported) |
| `ecdsa-p384` | ECDSA with NIST P-384 curve (higher security strength) |

Invalid values produce a config parse error.

### Staging Environment

Use Let's Encrypt's staging environment for testing to avoid rate limits:
Expand Down
41 changes: 41 additions & 0 deletions content/reference/config-schema.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,6 +141,47 @@ upstreams {
| `session-resumption` | bool | `true` | Enable session tickets |
| `cipher-suites` | list | - | Allowed cipher suites |

### ACME Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `email` | string | **required** | Contact email for ACME account |
| `domains` | string[] | **required** | Domains to include in certificate |
| `server-url` | string | - | Custom ACME directory URL (e.g., ZeroSSL) |
| `staging` | bool | `false` | Use Let's Encrypt staging environment |
| `eab` | block | - | External Account Binding credentials |
| `storage` | path | `/var/lib/zentinel/acme` | Certificate storage directory |
| `renew-before-days` | u32 | `30` | Days before expiry to trigger renewal |
| `challenge-type` | string | `"http-01"` | Challenge type: `http-01` or `dns-01` |
| `key-type` | string | `"ecdsa-p256"` | Key type: `ecdsa-p256`, `ecdsa-p384` |
| `dns-provider` | block | - | DNS provider config (required for dns-01) |

### EAB Options

| Option | Type | Description |
|--------|------|-------------|
| `kid` | string | Key ID provided by the ACME CA |
| `hmac-key` | string | HMAC key (base64url-encoded) from the CA |

### DNS Provider Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `type` | string | **required** | Provider: `cloudflare`, `hetzner`, `webhook` |
| `credentials-file` | path | - | Path to credentials file |
| `credentials-env` | string | - | Environment variable with credentials |
| `api-timeout-secs` | u64 | `30` | API request timeout |
| `propagation` | block | - | DNS propagation check settings |

### Propagation Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `initial-delay-secs` | u64 | `10` | Wait before first propagation check |
| `check-interval-secs` | u64 | `5` | Interval between checks |
| `timeout-secs` | u64 | `120` | Max time to wait for propagation |
| `nameservers` | string[] | public DNS | DNS servers to query |

## Routes Block

```kdl
Expand Down
160 changes: 160 additions & 0 deletions content/v/26.04/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,160 @@
+++
title = "Introduction"
weight = 0
sort_by = "weight"
template = "section.html"
+++
Welcome to **Zentinel** documentation version **26.04**.

> **Note**: You are viewing an archived version of the documentation. For the latest documentation, visit the [current version](/).

---

Welcome to **Zentinel**, a high-performance **reverse proxy** platform built on [Cloudflare's Pingora](https://github.com/cloudflare/pingora) framework. Zentinel extends Pingora's robust foundation with enterprise-grade features designed for modern web infrastructure.

## Key Features

### High Performance
- Built on Pingora's async Rust foundation
- Memory-safe architecture with zero-copy operations
- Efficient connection pooling and keep-alive management
- Optimized for both throughput and latency

### Service-Type Awareness
Zentinel understands different service types and optimizes behavior accordingly:

- **Web Applications**: HTML error pages, session handling, SPA support
- **REST APIs**: JSON schema validation, structured error responses, OpenAPI integration
- **Static Files**: Direct file serving, automatic MIME types, caching headers

### Advanced Routing
- Flexible path-based and host-based routing
- Route priorities and groups
- Path variables and pattern matching
- Per-route configuration overrides

### Comprehensive Error Handling
- Service-type-specific error formats (HTML, JSON, XML, Text)
- Custom error page templates with variable substitution
- Graceful fallbacks for connection failures
- Detailed error tracking with request IDs

### Observability
- Structured logging with configurable levels
- Prometheus-compatible metrics
- Distributed tracing support
- Health check endpoints

### Security Features
- Path traversal protection for static files
- Request validation and sanitization
- Rate limiting capabilities
- TLS/SSL with modern cipher suites
- HTTP/3 preparation with QUIC support (ready for activation)

### Configuration
- Human-friendly KDL configuration format
- Hot reload without downtime
- Environment variable substitution
- Comprehensive validation on startup

## Why Zentinel?

### Production-Ready
Zentinel is designed for production use from the ground up. Every feature is implemented with reliability, performance, and operational excellence in mind.

### Type-Safe and Memory-Safe
Written in Rust, Zentinel eliminates entire classes of bugs common in traditional proxies, including buffer overflows, use-after-free errors, and data races.

### Cloud-Native
Built for modern cloud environments with support for:
- Container deployments (Docker, Kubernetes)
- Horizontal scaling
- Service mesh integration
- Dynamic configuration

### Developer-Friendly
- Clear, expressive configuration
- Comprehensive error messages
- Extensive documentation
- Example configurations for common use cases

## Use Cases

Zentinel excels in various deployment scenarios:

- **API Gateway**: Validate requests, transform responses, implement rate limiting
- **Static Content Delivery**: Serve files directly with optimal caching headers
- **Load Balancer**: Distribute traffic across multiple upstream servers
- **Web Application Proxy**: Handle sessions, provide custom error pages, support SPAs
- **Microservices Router**: Route requests to different services based on paths
- **Edge Proxy**: Terminate SSL, implement security policies, cache responses

## Architecture Highlights

Zentinel leverages Pingora's battle-tested architecture while adding its own innovations:

```text
Client Request
↓
[TLS Termination]
↓
[Route Matching] ← Service Type Detection
↓
[Request Processing]
├─→ Static File Serving (no upstream)
├─→ API Validation → Upstream
└─→ Web App Processing → Upstream
↓
[Response Processing]
├─→ Error Page Generation
├─→ Header Manipulation
└─→ Caching Headers
↓
Client Response
```

## Getting Started

This documentation will guide you through:

1. **[Installation](./getting-started/installation.md)** — Get Zentinel up and running
2. **[Quick Start](./getting-started/quick-start.md)** — Your first proxy configuration
3. **[Core Concepts](./concepts/architecture.md)** — Understand how Zentinel works
4. **[Configuration](./configuration/file-format.md)** — Master the configuration system
5. **[Features](./features/)** — Explore all capabilities
6. **[Deployment](./deployment/docker.md)** — Deploy to production

## Documentation Structure

- **[Getting Started](./getting-started/)** — Installation and basic setup
- **[Core Concepts](./concepts/)** — Fundamental architecture and design principles
- **[Configuration](./configuration/)** — Detailed configuration reference
- **[Features](./features/)** — Complete feature list with code references
- **[Agents](./agents/)** — External agent system for extensibility
- **[Operations](./operations/)** — Production management and troubleshooting
- **[Deployment](./deployment/)** — Container and cloud deployment guides
- **[Control Plane](./control-plane/)** — Fleet management, rollouts, and observability
- **[Examples](./examples/)** — Real-world configuration examples
- **[Reference](./reference/)** — Metrics, CLI, and API documentation
- **[Development](./development/)** — Contributing to Zentinel

## Community

- 💬 **[Discussions](https://github.com/zentinelproxy/zentinel/discussions)** — Questions, ideas, show & tell
- 🐛 **[Issues](https://github.com/zentinelproxy/zentinel/issues)** — Bug reports and feature requests
- 📦 **[GitHub](https://github.com/zentinelproxy/zentinel)** — Source code and releases

Contributions are welcome! See our [Contributing Guide](./development/contributing.md) to get started.

## Version Information

This documentation covers Zentinel release **26.04** (archived). For the latest updates and changes, see the [Changelog](./appendix/changelog.md). For details on the versioning scheme, see [Versioning](./appendix/versioning.md).

## License

Zentinel is open-source software licensed under the Apache License, Version 2.0. See the [License](./appendix/license.md) page for details.

---

Ready to get started? Head to the [Installation Guide](./getting-started/installation.md) to begin your journey with Zentinel!
Loading
Loading