docs: complete feature documentation rewrite
Comprehensive documentation overhaul for Charon features: Rewrite features.md as marketing overview (87% reduction) Create comprehensive dns-challenge.md for new DNS feature Expand 18 feature stub pages into complete documentation: SSL certificates, CrowdSec, WAF, ACLs, rate limiting Security headers, proxy headers, web UI, Docker integration Caddyfile import, logs, WebSocket, backup/restore Live reload, localization, API, UI themes, supply chain security Update README.md with DNS Challenge in Top Features Total: ~2,000+ lines of new user-facing documentation Refs: #21, #461
This commit is contained in:
GitHub Actions
@@ -9,16 +9,89 @@ Define exactly who can access what. Block specific countries, allow only certain
|
||||
|
||||
## Overview
|
||||
|
||||
<!-- TODO: Add detailed overview -->
|
||||
Access Control Lists let you create granular rules that determine who can reach your proxied services. Rules are evaluated in order, and the first matching rule determines whether access is allowed or denied.
|
||||
|
||||
Coming soon.
|
||||
ACL capabilities:
|
||||
|
||||
- **IP Allowlists** — Only permit specific IPs or ranges
|
||||
- **IP Blocklists** — Deny access from known bad actors
|
||||
- **Country/Geo Blocking** — Restrict access by geographic location
|
||||
- **CIDR Support** — Define rules using network ranges (e.g., `192.168.1.0/24`)
|
||||
|
||||
## Why Use This
|
||||
|
||||
- **Compliance** — Restrict access to specific regions for data sovereignty
|
||||
- **Security** — Block high-risk countries or known malicious networks
|
||||
- **Internal Services** — Limit access to corporate IP ranges
|
||||
- **Layered Defense** — Combine with WAF and CrowdSec for comprehensive protection
|
||||
|
||||
## Configuration
|
||||
|
||||
<!-- TODO: Add configuration steps -->
|
||||
### Creating an Access List
|
||||
|
||||
Coming soon.
|
||||
1. Navigate to **Access Lists** in the sidebar
|
||||
2. Click **Add Access List**
|
||||
3. Provide a descriptive name (e.g., "Office IPs Only")
|
||||
4. Configure your rules
|
||||
|
||||
### Rule Types
|
||||
|
||||
#### IP Range Filtering
|
||||
|
||||
Add specific IPs or CIDR ranges:
|
||||
|
||||
```text
|
||||
Allow: 192.168.1.0/24 # Allow entire subnet
|
||||
Allow: 10.0.0.5 # Allow single IP
|
||||
Deny: 0.0.0.0/0 # Deny everything else
|
||||
```
|
||||
|
||||
Rules are processed top-to-bottom. Place more specific rules before broader ones.
|
||||
|
||||
#### Country/Geo Blocking
|
||||
|
||||
Block or allow traffic by country:
|
||||
|
||||
1. In the Access List editor, go to **Country Rules**
|
||||
2. Select countries to **Allow** or **Deny**
|
||||
3. Choose default action for unlisted countries
|
||||
|
||||
Common configurations:
|
||||
|
||||
- **Allow only your country** — Whitelist your country, deny all others
|
||||
- **Block high-risk regions** — Deny specific countries, allow rest
|
||||
- **Compliance zones** — Allow only EU countries for GDPR compliance
|
||||
|
||||
### Applying to Proxy Hosts
|
||||
|
||||
1. Edit your proxy host
|
||||
2. Go to the **Access** tab
|
||||
3. Select your Access List from the dropdown
|
||||
4. Save changes
|
||||
|
||||
Each proxy host can have one Access List assigned. Create multiple lists for different access patterns.
|
||||
|
||||
## Rule Evaluation Order
|
||||
|
||||
```text
|
||||
1. Check IP allowlist → Allow if matched
|
||||
2. Check IP blocklist → Deny if matched
|
||||
3. Check country rules → Allow/Deny based on geo
|
||||
4. Apply default action
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
| Scenario | Recommendation |
|
||||
|----------|----------------|
|
||||
| Internal admin panels | Allowlist office/VPN IPs only |
|
||||
| Public websites | Use geo-blocking for high-risk regions |
|
||||
| API endpoints | Combine IP rules with rate limiting |
|
||||
| Development servers | Restrict to developer IPs |
|
||||
|
||||
## Related
|
||||
|
||||
- [Proxy Hosts](./proxy-hosts.md) — Apply access lists to services
|
||||
- [CrowdSec Integration](./crowdsec.md) — Automatic threat-based blocking
|
||||
- [Rate Limiting](./rate-limiting.md) — Limit request frequency
|
||||
- [Back to Features](../features.md)
|
||||
|
||||
@@ -9,16 +9,153 @@ Automate everything. Charon's comprehensive REST API lets you manage hosts, cert
|
||||
|
||||
## Overview
|
||||
|
||||
<!-- TODO: Add detailed overview -->
|
||||
The REST API provides full control over Charon's functionality through HTTP endpoints. All responses are JSON-formatted, and the API follows RESTful conventions for resource management.
|
||||
|
||||
Coming soon.
|
||||
**Base URL**: `http://your-charon-instance:81/api`
|
||||
|
||||
## Configuration
|
||||
### Authentication
|
||||
|
||||
<!-- TODO: Add configuration steps -->
|
||||
All API requests require a Bearer token. Generate tokens in **Settings → API Tokens**.
|
||||
|
||||
Coming soon.
|
||||
```bash
|
||||
# Include in all requests
|
||||
Authorization: Bearer your-api-token-here
|
||||
```
|
||||
|
||||
Tokens support granular permissions:
|
||||
- **Read-only**: View configurations without modification
|
||||
- **Full access**: Complete CRUD operations
|
||||
- **Scoped**: Limit to specific resource types
|
||||
|
||||
## Why Use the API?
|
||||
|
||||
| Use Case | Benefit |
|
||||
|----------|---------|
|
||||
| **CI/CD Pipelines** | Automatically create proxy hosts for staging/preview deployments |
|
||||
| **Infrastructure as Code** | Version control your Charon configuration |
|
||||
| **Custom Dashboards** | Build monitoring integrations |
|
||||
| **Bulk Operations** | Manage hundreds of hosts programmatically |
|
||||
| **GitOps Workflows** | Sync configuration from Git repositories |
|
||||
|
||||
## Key Endpoints
|
||||
|
||||
### Proxy Hosts
|
||||
|
||||
```bash
|
||||
# List all proxy hosts
|
||||
curl -X GET "http://charon:81/api/nginx/proxy-hosts" \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
|
||||
# Create a proxy host
|
||||
curl -X POST "http://charon:81/api/nginx/proxy-hosts" \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"domain_names": ["app.example.com"],
|
||||
"forward_host": "10.0.0.5",
|
||||
"forward_port": 3000,
|
||||
"ssl_forced": true,
|
||||
"certificate_id": 1
|
||||
}'
|
||||
|
||||
# Update a proxy host
|
||||
curl -X PUT "http://charon:81/api/nginx/proxy-hosts/1" \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"forward_port": 8080}'
|
||||
|
||||
# Delete a proxy host
|
||||
curl -X DELETE "http://charon:81/api/nginx/proxy-hosts/1" \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
```
|
||||
|
||||
### SSL Certificates
|
||||
|
||||
```bash
|
||||
# List certificates
|
||||
curl -X GET "http://charon:81/api/nginx/certificates" \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
|
||||
# Request new Let's Encrypt certificate
|
||||
curl -X POST "http://charon:81/api/nginx/certificates" \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"provider": "letsencrypt",
|
||||
"domain_names": ["secure.example.com"],
|
||||
"meta": {"dns_challenge": true, "dns_provider": "cloudflare"}
|
||||
}'
|
||||
```
|
||||
|
||||
### DNS Providers
|
||||
|
||||
```bash
|
||||
# List configured DNS providers
|
||||
curl -X GET "http://charon:81/api/nginx/dns-providers" \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
|
||||
# Add a DNS provider (for DNS-01 challenges)
|
||||
curl -X POST "http://charon:81/api/nginx/dns-providers" \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "Cloudflare Production",
|
||||
"acme_dns_provider": "cloudflare",
|
||||
"meta": {"CF_API_TOKEN": "your-cloudflare-token"}
|
||||
}'
|
||||
```
|
||||
|
||||
### Security Settings
|
||||
|
||||
```bash
|
||||
# Get WAF status
|
||||
curl -X GET "http://charon:81/api/security/waf" \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
|
||||
# Enable WAF for a host
|
||||
curl -X PUT "http://charon:81/api/nginx/proxy-hosts/1" \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"waf_enabled": true, "waf_mode": "block"}'
|
||||
|
||||
# List CrowdSec decisions
|
||||
curl -X GET "http://charon:81/api/security/crowdsec/decisions" \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
```
|
||||
|
||||
## CI/CD Integration Example
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
```yaml
|
||||
- name: Create Preview Environment
|
||||
run: |
|
||||
curl -X POST "${{ secrets.CHARON_URL }}/api/nginx/proxy-hosts" \
|
||||
-H "Authorization: Bearer ${{ secrets.CHARON_TOKEN }}" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"domain_names": ["pr-${{ github.event.number }}.preview.example.com"],
|
||||
"forward_host": "${{ steps.deploy.outputs.ip }}",
|
||||
"forward_port": 3000
|
||||
}'
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
The API returns standard HTTP status codes:
|
||||
|
||||
| Code | Meaning |
|
||||
|------|---------|
|
||||
| `200` | Success |
|
||||
| `201` | Resource created |
|
||||
| `400` | Invalid request body |
|
||||
| `401` | Invalid or missing token |
|
||||
| `403` | Insufficient permissions |
|
||||
| `404` | Resource not found |
|
||||
| `500` | Server error |
|
||||
|
||||
## Related
|
||||
|
||||
- [Backup & Restore](backup-restore.md) - API-managed backups
|
||||
- [SSL Certificates](ssl-certificates.md) - Certificate automation
|
||||
- [Back to Features](../features.md)
|
||||
|
||||
@@ -9,16 +9,76 @@ Your configuration is valuable. Charon makes it easy to backup your entire setup
|
||||
|
||||
## Overview
|
||||
|
||||
<!-- TODO: Add detailed overview -->
|
||||
Charon provides automatic configuration backups and one-click restore functionality. Your proxy hosts, SSL certificates, access lists, and settings are all preserved, ensuring you can recover quickly from any situation.
|
||||
|
||||
Coming soon.
|
||||
Backups are stored within the Charon data directory and can be downloaded for off-site storage.
|
||||
|
||||
## Configuration
|
||||
## Why Use This
|
||||
|
||||
<!-- TODO: Add configuration steps -->
|
||||
- **Disaster Recovery**: Restore your entire configuration in seconds
|
||||
- **Migration Made Easy**: Move to new hardware without reconfiguring
|
||||
- **Change Confidence**: Make changes knowing you can roll back
|
||||
- **Audit Trail**: Keep historical snapshots of your configuration
|
||||
|
||||
Coming soon.
|
||||
## What Gets Backed Up
|
||||
|
||||
| Component | Included |
|
||||
|-----------|----------|
|
||||
| **Database** | All proxy hosts, redirects, streams, and 404 hosts |
|
||||
| **SSL Certificates** | Let's Encrypt certificates and custom certificates |
|
||||
| **Access Lists** | All access control configurations |
|
||||
| **Users** | User accounts and permissions |
|
||||
| **Settings** | Application preferences and configurations |
|
||||
| **CrowdSec Config** | Security settings and custom rules |
|
||||
|
||||
## Creating Backups
|
||||
|
||||
### Automatic Backups
|
||||
|
||||
Charon creates automatic backups:
|
||||
|
||||
- Before major configuration changes
|
||||
- On a configurable schedule (default: daily)
|
||||
- Before version upgrades
|
||||
|
||||
### Manual Backups
|
||||
|
||||
To create a manual backup:
|
||||
|
||||
1. Navigate to **Settings** → **Backup**
|
||||
2. Click **Create Backup**
|
||||
3. Optionally download the backup file for off-site storage
|
||||
|
||||
## Restoring from Backup
|
||||
|
||||
To restore a previous configuration:
|
||||
|
||||
1. Navigate to **Settings** → **Backup**
|
||||
2. Select the backup to restore from the list
|
||||
3. Click **Restore**
|
||||
4. Confirm the restoration
|
||||
|
||||
> **Note**: Restoring a backup will overwrite current settings. Consider creating a backup of your current state first.
|
||||
|
||||
## Backup Retention
|
||||
|
||||
Charon manages backup storage automatically:
|
||||
|
||||
- **Automatic backups**: Retained for 30 days
|
||||
- **Manual backups**: Retained indefinitely until deleted
|
||||
- **Pre-upgrade backups**: Retained for 90 days
|
||||
|
||||
Configure retention settings in **Settings** → **Backup** → **Retention Policy**.
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Download backups regularly** for off-site storage
|
||||
2. **Test restores** periodically to ensure backups are valid
|
||||
3. **Backup before changes** when modifying critical configurations
|
||||
4. **Label manual backups** with descriptive names
|
||||
|
||||
## Related
|
||||
|
||||
- [Zero-Downtime Updates](live-reload.md)
|
||||
- [Settings](../getting-started/configuration.md)
|
||||
- [Back to Features](../features.md)
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
title: Caddyfile Import
|
||||
description: Import existing Caddyfile configurations with one click
|
||||
category: migration
|
||||
---
|
||||
|
||||
# Caddyfile Import
|
||||
@@ -9,16 +10,166 @@ Migrating from another Caddy setup? Import your existing Caddyfile configuration
|
||||
|
||||
## Overview
|
||||
|
||||
<!-- TODO: Add detailed overview -->
|
||||
Caddyfile import parses your existing Caddy configuration files and converts them into Charon-managed hosts. This enables smooth migration from standalone Caddy installations, other Caddy-based tools, or configuration backups.
|
||||
|
||||
Coming soon.
|
||||
### Supported Configurations
|
||||
|
||||
## Configuration
|
||||
- **Reverse Proxy Sites**: Domain → backend mappings
|
||||
- **File Server Sites**: Static file hosting configurations
|
||||
- **TLS Settings**: Certificate paths and ACME settings
|
||||
- **Headers**: Custom header configurations
|
||||
- **Redirects**: Redirect rules and rewrites
|
||||
|
||||
<!-- TODO: Add configuration steps -->
|
||||
## Why Use This
|
||||
|
||||
Coming soon.
|
||||
### Preserve Existing Work
|
||||
|
||||
- Don't rebuild configurations from scratch
|
||||
- Maintain proven routing rules
|
||||
- Keep customizations intact
|
||||
|
||||
### Reduce Migration Risk
|
||||
|
||||
- Preview imports before applying
|
||||
- Identify conflicts and duplicates
|
||||
- Rollback if issues occur
|
||||
|
||||
### Accelerate Adoption
|
||||
|
||||
- Evaluate Charon without commitment
|
||||
- Run imports on staging first
|
||||
- Gradual migration at your pace
|
||||
|
||||
## How to Import
|
||||
|
||||
### Step 1: Access Import Tool
|
||||
|
||||
1. Navigate to **Settings** → **Import / Export**
|
||||
2. Click **Import Caddyfile**
|
||||
|
||||
### Step 2: Provide Configuration
|
||||
|
||||
Choose one of three methods:
|
||||
|
||||
**Paste Content:**
|
||||
```
|
||||
example.com {
|
||||
reverse_proxy localhost:3000
|
||||
}
|
||||
|
||||
api.example.com {
|
||||
reverse_proxy localhost:8080
|
||||
}
|
||||
```
|
||||
|
||||
**Upload File:**
|
||||
- Click **Choose File**
|
||||
- Select your Caddyfile
|
||||
|
||||
**Fetch from URL:**
|
||||
- Enter URL to raw Caddyfile content
|
||||
- Useful for version-controlled configurations
|
||||
|
||||
### Step 3: Preview and Confirm
|
||||
|
||||
The import preview shows:
|
||||
|
||||
- **Hosts Found**: Number of site blocks detected
|
||||
- **Parse Warnings**: Non-fatal issues or unsupported directives
|
||||
- **Conflicts**: Domains that already exist in Charon
|
||||
|
||||
### Step 4: Execute Import
|
||||
|
||||
Click **Import** to create hosts. The process handles each host individually—one failure doesn't block others.
|
||||
|
||||
## Import Results Modal
|
||||
|
||||
After import completes, a summary modal displays:
|
||||
|
||||
| Category | Description |
|
||||
|----------|-------------|
|
||||
| **Created** | New hosts added to Charon |
|
||||
| **Updated** | Existing hosts modified (if overwrite enabled) |
|
||||
| **Skipped** | Hosts skipped due to conflicts or errors |
|
||||
| **Warnings** | Non-blocking issues to review |
|
||||
|
||||
### Example Results
|
||||
|
||||
```
|
||||
Import Complete
|
||||
|
||||
✓ Created: 12 hosts
|
||||
↻ Updated: 3 hosts
|
||||
○ Skipped: 2 hosts
|
||||
⚠ Warnings: 1
|
||||
|
||||
Details:
|
||||
✓ example.com → localhost:3000
|
||||
✓ api.example.com → localhost:8080
|
||||
○ old.example.com (already exists, overwrite disabled)
|
||||
⚠ staging.example.com (unsupported directive: php_fastcgi)
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
### Overwrite Existing
|
||||
|
||||
| Setting | Behavior |
|
||||
|---------|----------|
|
||||
| **Off** (default) | Skip hosts that already exist |
|
||||
| **On** | Replace existing hosts with imported configuration |
|
||||
|
||||
### Import Disabled Hosts
|
||||
|
||||
Create hosts but leave them disabled for review before enabling.
|
||||
|
||||
### TLS Handling
|
||||
|
||||
| Source TLS Setting | Charon Behavior |
|
||||
|--------------------|-----------------|
|
||||
| ACME configured | Enable Let's Encrypt |
|
||||
| Custom certificates | Create host, flag for manual cert upload |
|
||||
| No TLS | Create HTTP-only host |
|
||||
|
||||
## Migration from Other Caddy Setups
|
||||
|
||||
### From Caddy Standalone
|
||||
|
||||
1. Locate your Caddyfile (typically `/etc/caddy/Caddyfile`)
|
||||
2. Copy contents or upload file
|
||||
3. Import into Charon
|
||||
4. Verify hosts work correctly
|
||||
5. Point DNS to Charon
|
||||
6. Decommission old Caddy
|
||||
|
||||
### From Other Management Tools
|
||||
|
||||
Export Caddyfile from your current tool, then import into Charon. Most Caddy-based tools provide export functionality.
|
||||
|
||||
### Partial Migrations
|
||||
|
||||
Import specific site blocks by editing the Caddyfile before import. Remove sites you want to migrate later or manage separately.
|
||||
|
||||
## Limitations
|
||||
|
||||
Some Caddyfile features require manual configuration after import:
|
||||
|
||||
- Custom plugins/modules
|
||||
- Complex matcher expressions
|
||||
- Snippet references (imported inline)
|
||||
- Global options (applied separately)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Issue | Solution |
|
||||
|-------|----------|
|
||||
| Parse error | Check Caddyfile syntax validity |
|
||||
| Missing hosts | Ensure site blocks have valid domains |
|
||||
| TLS warnings | Configure certificates manually post-import |
|
||||
| Duplicate domains | Enable overwrite or rename in source |
|
||||
|
||||
## Related
|
||||
|
||||
- [Web UI](web-ui.md) - Managing imported hosts
|
||||
- [SSL Certificates](ssl-certificates.md) - Certificate configuration
|
||||
- [Back to Features](../features.md)
|
||||
|
||||
@@ -9,16 +9,83 @@ Protect your applications using behavior-based threat detection powered by a glo
|
||||
|
||||
## Overview
|
||||
|
||||
<!-- TODO: Add detailed overview -->
|
||||
CrowdSec analyzes your traffic patterns and blocks malicious behavior in real-time. Unlike traditional firewalls that rely on static rules, CrowdSec uses behavioral analysis and crowdsourced threat intelligence to identify and stop attacks.
|
||||
|
||||
Coming soon.
|
||||
Key capabilities:
|
||||
|
||||
- **Behavior Detection** — Identifies attack patterns like brute-force, scanning, and exploitation
|
||||
- **Community Blocklists** — Benefit from threats detected by the global CrowdSec community
|
||||
- **Real-time Blocking** — Malicious IPs are blocked immediately via Caddy integration
|
||||
- **Automatic Updates** — Threat intelligence updates continuously
|
||||
|
||||
## Why Use This
|
||||
|
||||
- **Proactive Defense** — Block attackers before they succeed
|
||||
- **Zero False Positives** — Behavioral analysis reduces incorrect blocks
|
||||
- **Community Intelligence** — Leverage data from thousands of CrowdSec users
|
||||
- **GUI-Controlled** — Enable/disable directly from the UI, no environment variables needed
|
||||
|
||||
## Configuration
|
||||
|
||||
<!-- TODO: Add configuration steps -->
|
||||
### Enabling CrowdSec
|
||||
|
||||
Coming soon.
|
||||
1. Navigate to **Settings → Security**
|
||||
2. Toggle **CrowdSec Protection** to enabled
|
||||
3. CrowdSec starts automatically and persists across container restarts
|
||||
|
||||
No environment variables or manual configuration required.
|
||||
|
||||
### Hub Presets
|
||||
|
||||
Access pre-built security configurations from the CrowdSec Hub:
|
||||
|
||||
1. Go to **Settings → Security → Hub Presets**
|
||||
2. Browse available collections (e.g., `crowdsecurity/nginx`, `crowdsecurity/http-cve`)
|
||||
3. Search for specific parsers, scenarios, or collections
|
||||
4. Click **Install** to add to your configuration
|
||||
|
||||
Popular presets include:
|
||||
|
||||
- **HTTP Probing** — Detect reconnaissance and scanning
|
||||
- **Bad User-Agents** — Block known malicious bots
|
||||
- **CVE Exploits** — Protection against known vulnerabilities
|
||||
|
||||
### Console Enrollment
|
||||
|
||||
Connect to the CrowdSec Console for centralized management:
|
||||
|
||||
1. Go to **Settings → Security → Console Enrollment**
|
||||
2. Enter your enrollment key from [console.crowdsec.net](https://console.crowdsec.net)
|
||||
3. Click **Enroll**
|
||||
|
||||
The Console provides:
|
||||
|
||||
- Multi-instance management
|
||||
- Historical attack data
|
||||
- Alert notifications
|
||||
- Blocklist subscriptions
|
||||
|
||||
### Live Decisions
|
||||
|
||||
View active blocks in real-time:
|
||||
|
||||
1. Navigate to **Security → Live Decisions**
|
||||
2. See all currently blocked IPs with:
|
||||
- IP address and origin country
|
||||
- Reason for block (scenario triggered)
|
||||
- Duration remaining
|
||||
- Option to manually unban
|
||||
|
||||
## Automatic Startup & Persistence
|
||||
|
||||
CrowdSec settings are stored in Charon's database and synchronized with the Security Config:
|
||||
|
||||
- **On Container Start** — CrowdSec launches automatically if previously enabled
|
||||
- **Configuration Sync** — Changes in the UI immediately apply to CrowdSec
|
||||
- **State Persistence** — Decisions and configurations survive restarts
|
||||
|
||||
## Related
|
||||
|
||||
- [Web Application Firewall](./waf.md) — Complement CrowdSec with WAF protection
|
||||
- [Access Control](./access-control.md) — Manual IP blocking and geo-restrictions
|
||||
- [Back to Features](../features.md)
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
title: Docker Auto-Discovery
|
||||
description: Automatically find and proxy Docker containers with one click
|
||||
category: integration
|
||||
---
|
||||
|
||||
# Docker Auto-Discovery
|
||||
@@ -9,16 +10,142 @@ Already running apps in Docker? Charon automatically finds your containers and o
|
||||
|
||||
## Overview
|
||||
|
||||
<!-- TODO: Add detailed overview -->
|
||||
Docker auto-discovery eliminates manual IP address hunting and port memorization. Charon queries the Docker API to list running containers, extracts their network information, and lets you create proxy configurations with a single click.
|
||||
|
||||
Coming soon.
|
||||
### How It Works
|
||||
|
||||
1. Charon connects to Docker via socket or TCP
|
||||
2. Queries running containers and their exposed ports
|
||||
3. Displays container list with network details
|
||||
4. You select a container and assign a domain
|
||||
5. Charon creates the proxy configuration automatically
|
||||
|
||||
## Why Use This
|
||||
|
||||
### Eliminate IP Address Hunting
|
||||
|
||||
- No more running `docker inspect` to find container IPs
|
||||
- No more updating configs when containers restart with new IPs
|
||||
- Container name resolution handles dynamic addressing
|
||||
|
||||
### Accelerate Development
|
||||
|
||||
- Spin up a new service, proxy it in seconds
|
||||
- Test different versions by proxying multiple containers
|
||||
- Remove proxies as easily as you create them
|
||||
|
||||
### Simplify Team Workflows
|
||||
|
||||
- Developers create their own proxy entries
|
||||
- No central config file bottlenecks
|
||||
- Self-service infrastructure access
|
||||
|
||||
## Configuration
|
||||
|
||||
<!-- TODO: Add configuration steps -->
|
||||
### Docker Socket Mounting
|
||||
|
||||
Coming soon.
|
||||
For Charon to discover containers, it needs Docker API access.
|
||||
|
||||
**Docker Compose:**
|
||||
```yaml
|
||||
services:
|
||||
charon:
|
||||
image: charon:latest
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock:ro
|
||||
```
|
||||
|
||||
**Docker Run:**
|
||||
```bash
|
||||
docker run -v /var/run/docker.sock:/var/run/docker.sock:ro charon
|
||||
```
|
||||
|
||||
> **Security Note**: The socket grants significant access. Use read-only mode (`:ro`) and consider Docker socket proxies for production.
|
||||
|
||||
### Remote Docker Server Support
|
||||
|
||||
Connect to Docker hosts over TCP:
|
||||
|
||||
1. Go to **Settings** → **Docker**
|
||||
2. Click **Add Remote Host**
|
||||
3. Enter connection details:
|
||||
- **Name**: Friendly identifier
|
||||
- **Host**: IP or hostname
|
||||
- **Port**: Docker API port (default: 2375/2376)
|
||||
- **TLS**: Enable for secure connections
|
||||
4. Upload TLS certificates if required
|
||||
5. Click **Test Connection**, then **Save**
|
||||
|
||||
## Container Selection Workflow
|
||||
|
||||
### Viewing Available Containers
|
||||
|
||||
1. Navigate to **Hosts** → **Add Host**
|
||||
2. Click **Select from Docker**
|
||||
3. Choose Docker host (local or remote)
|
||||
4. Browse running containers
|
||||
|
||||
### Container List Display
|
||||
|
||||
Each container shows:
|
||||
|
||||
- **Name**: Container name
|
||||
- **Image**: Source image and tag
|
||||
- **Ports**: Exposed ports and mappings
|
||||
- **Networks**: Connected Docker networks
|
||||
- **Status**: Running, paused, etc.
|
||||
|
||||
### Creating a Proxy
|
||||
|
||||
1. Click a container row to select it
|
||||
2. If multiple ports are exposed, choose the target port
|
||||
3. Enter the domain name for this proxy
|
||||
4. Configure SSL options
|
||||
5. Click **Create Host**
|
||||
|
||||
### Automatic Updates
|
||||
|
||||
When containers restart:
|
||||
|
||||
- Charon continues proxying to the container name
|
||||
- Docker's internal DNS resolves the new IP
|
||||
- No manual intervention required
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
### Network Selection
|
||||
|
||||
If a container is on multiple networks, specify which network Charon should use for routing:
|
||||
|
||||
1. Edit the host after creation
|
||||
2. Go to **Advanced** → **Docker**
|
||||
3. Select the preferred network
|
||||
|
||||
### Port Override
|
||||
|
||||
Override the auto-detected port:
|
||||
|
||||
1. Edit the host
|
||||
2. Change the backend URL port manually
|
||||
3. Useful for containers with non-standard port configurations
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Issue | Cause | Solution |
|
||||
|-------|-------|----------|
|
||||
| No containers shown | Socket not mounted | Add Docker socket volume |
|
||||
| Connection refused | Remote Docker not configured | Enable TCP API on Docker host |
|
||||
| Container not proxied | Container not running | Start the container |
|
||||
| Wrong IP resolved | Multi-network container | Specify network in advanced settings |
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- **Socket Access**: Docker socket provides root-equivalent access. Mount read-only.
|
||||
- **Remote Connections**: Always use TLS for remote Docker hosts.
|
||||
- **Network Isolation**: Use Docker networks to segment container communication.
|
||||
|
||||
## Related
|
||||
|
||||
- [Web UI](web-ui.md) - Point & click management
|
||||
- [SSL Certificates](ssl-certificates.md) - Automatic HTTPS for proxied containers
|
||||
- [Back to Features](../features.md)
|
||||
|
||||
@@ -9,16 +9,74 @@ Make changes without interrupting your users. Update domains, modify security ru
|
||||
|
||||
## Overview
|
||||
|
||||
<!-- TODO: Add detailed overview -->
|
||||
Charon leverages Caddy's live reload capability to apply configuration changes without dropping connections. When you save changes in the UI, Caddy gracefully transitions to the new configuration while maintaining all active connections.
|
||||
|
||||
Coming soon.
|
||||
This means your users experience zero interruption—even during significant configuration changes.
|
||||
|
||||
## Configuration
|
||||
## Why Use This
|
||||
|
||||
<!-- TODO: Add configuration steps -->
|
||||
- **No Downtime**: Active connections remain unaffected
|
||||
- **Instant Changes**: New configuration takes effect immediately
|
||||
- **Safe Iteration**: Make frequent adjustments without risk
|
||||
- **Production Friendly**: Update live systems confidently
|
||||
|
||||
Coming soon.
|
||||
## How It Works
|
||||
|
||||
When you save configuration changes:
|
||||
|
||||
1. Charon generates updated Caddy configuration
|
||||
2. Caddy validates the new configuration
|
||||
3. If valid, Caddy atomically swaps to the new config
|
||||
4. Existing connections continue on old config until complete
|
||||
5. New connections use the updated configuration
|
||||
|
||||
The entire process typically completes in milliseconds.
|
||||
|
||||
## What Can Be Changed Live
|
||||
|
||||
These changes apply instantly without any restart:
|
||||
|
||||
| Change Type | Live Reload |
|
||||
|-------------|-------------|
|
||||
| Add/remove proxy hosts | ✅ Yes |
|
||||
| Modify upstream servers | ✅ Yes |
|
||||
| Update SSL certificates | ✅ Yes |
|
||||
| Change access lists | ✅ Yes |
|
||||
| Modify headers | ✅ Yes |
|
||||
| Update redirects | ✅ Yes |
|
||||
| Add/remove domains | ✅ Yes |
|
||||
|
||||
## CrowdSec Integration Note
|
||||
|
||||
> **Important**: CrowdSec integration requires a one-time container restart when first enabled or when changing the CrowdSec API endpoint.
|
||||
|
||||
After the initial setup, CrowdSec decisions update automatically without restart. Only the connection to the CrowdSec API requires the restart.
|
||||
|
||||
To minimize disruption:
|
||||
|
||||
1. Configure CrowdSec during a maintenance window
|
||||
2. After restart, all future updates are live
|
||||
|
||||
## Validation and Rollback
|
||||
|
||||
Charon validates all configuration changes before applying:
|
||||
|
||||
- **Syntax Validation**: Catches configuration errors
|
||||
- **Connection Testing**: Verifies upstream availability
|
||||
- **Automatic Rollback**: Invalid configs are rejected
|
||||
|
||||
If validation fails, your current configuration remains active and an error message explains the issue.
|
||||
|
||||
## Monitoring Changes
|
||||
|
||||
View configuration change history:
|
||||
|
||||
1. Check the **Real-Time Logs** for reload events
|
||||
2. Review **Settings** → **Backup** for configuration snapshots
|
||||
|
||||
## Related
|
||||
|
||||
- [Backup & Restore](backup-restore.md)
|
||||
- [Real-Time Logs](logs.md)
|
||||
- [CrowdSec Integration](crowdsec.md)
|
||||
- [Back to Features](../features.md)
|
||||
|
||||
@@ -9,16 +9,77 @@ Charon speaks your language. The interface is available in English, Spanish, Fre
|
||||
|
||||
## Overview
|
||||
|
||||
<!-- TODO: Add detailed overview -->
|
||||
Charon's interface is fully localized, making it accessible to users worldwide. All UI elements, error messages, and documentation links adapt to your selected language. Language switching happens instantly in the browser without requiring a page reload or server restart.
|
||||
|
||||
Coming soon.
|
||||
## Supported Languages
|
||||
|
||||
## Configuration
|
||||
| Language | Code | Status |
|
||||
|----------|------|--------|
|
||||
| English | `en` | Complete (default) |
|
||||
| Spanish | `es` | Complete |
|
||||
| French | `fr` | Complete |
|
||||
| German | `de` | Complete |
|
||||
| Chinese (Simplified) | `zh` | Complete |
|
||||
|
||||
<!-- TODO: Add configuration steps -->
|
||||
## Why Use This
|
||||
|
||||
Coming soon.
|
||||
- **Native Experience**: Use Charon in your preferred language
|
||||
- **Team Accessibility**: Support multilingual teams
|
||||
- **Instant Switching**: Change languages without interruption
|
||||
- **Complete Coverage**: All UI elements are translated
|
||||
|
||||
## Changing Language
|
||||
|
||||
To change the interface language:
|
||||
|
||||
1. Click your **username** in the top-right corner
|
||||
2. Select **Settings**
|
||||
3. Find the **Language** dropdown
|
||||
4. Select your preferred language
|
||||
|
||||
The interface updates immediately—no reload required.
|
||||
|
||||
### Per-User Setting
|
||||
|
||||
Language preference is stored per user account. Each team member can use Charon in their preferred language independently.
|
||||
|
||||
## Browser Language Detection
|
||||
|
||||
On first visit, Charon attempts to detect your browser's language preference. If a supported language matches, it's selected automatically. You can override this in settings at any time.
|
||||
|
||||
## What Gets Translated
|
||||
|
||||
- Navigation menus and buttons
|
||||
- Form labels and placeholders
|
||||
- Error and success messages
|
||||
- Tooltips and help text
|
||||
- Confirmation dialogs
|
||||
|
||||
## What Stays in English
|
||||
|
||||
Some technical content remains in English for consistency:
|
||||
|
||||
- Log messages (from Caddy/CrowdSec)
|
||||
- API responses
|
||||
- Configuration file syntax
|
||||
- Domain names and URLs
|
||||
|
||||
## Contributing Translations
|
||||
|
||||
Help improve Charon's translations or add new languages:
|
||||
|
||||
1. Review the [Contributing Translations Guide](../../CONTRIBUTING_TRANSLATIONS.md)
|
||||
2. Translation files are in the frontend `locales/` directory
|
||||
3. Submit improvements via pull request
|
||||
|
||||
We welcome contributions for:
|
||||
|
||||
- New language additions
|
||||
- Translation corrections
|
||||
- Context improvements
|
||||
|
||||
## Related
|
||||
|
||||
- [Contributing Translations](../../CONTRIBUTING_TRANSLATIONS.md)
|
||||
- [Settings](../getting-started/configuration.md)
|
||||
- [Back to Features](../features.md)
|
||||
|
||||
@@ -9,16 +9,66 @@ Watch requests flow through your proxy in real-time. Filter by domain, status co
|
||||
|
||||
## Overview
|
||||
|
||||
<!-- TODO: Add detailed overview -->
|
||||
Charon provides real-time log streaming via WebSocket, giving you instant visibility into all proxy traffic and security events. The logging system includes two main views:
|
||||
|
||||
Coming soon.
|
||||
- **Access Logs**: All HTTP requests flowing through Caddy
|
||||
- **Security Logs**: Cerberus Dashboard showing CrowdSec decisions and WAF events
|
||||
|
||||
## Configuration
|
||||
Logs stream directly to your browser with minimal latency, eliminating the need to SSH into containers or parse log files manually.
|
||||
|
||||
<!-- TODO: Add configuration steps -->
|
||||
## Why Use This
|
||||
|
||||
Coming soon.
|
||||
- **Instant Troubleshooting**: See requests as they happen to diagnose issues in real-time
|
||||
- **Security Monitoring**: Watch for blocked threats and suspicious activity
|
||||
- **No CLI Required**: Everything accessible through the web interface
|
||||
- **Persistent Connection**: WebSocket keeps the stream open without polling
|
||||
|
||||
## Log Viewer Controls
|
||||
|
||||
The log viewer provides intuitive controls for managing the log stream:
|
||||
|
||||
| Control | Function |
|
||||
|---------|----------|
|
||||
| **Pause/Resume** | Temporarily stop the stream to examine specific entries |
|
||||
| **Clear** | Remove all displayed logs (doesn't affect server logs) |
|
||||
| **Auto-scroll** | Automatically scroll to newest entries (toggle on/off) |
|
||||
|
||||
## Filtering Options
|
||||
|
||||
Filter logs to focus on what matters:
|
||||
|
||||
- **Level**: Filter by severity (info, warning, error)
|
||||
- **Source**: Filter by service (caddy, crowdsec, cerberus)
|
||||
- **Text Search**: Free-text search across all log fields
|
||||
- **Time Range**: View logs from specific time periods
|
||||
|
||||
### Server-Side Query Parameters
|
||||
|
||||
For advanced filtering, use query parameters when connecting:
|
||||
|
||||
```text
|
||||
/api/logs/stream?level=error&source=crowdsec&limit=1000
|
||||
```
|
||||
|
||||
## WebSocket Connection
|
||||
|
||||
The log viewer displays connection status in the header:
|
||||
|
||||
- **Connected**: Green indicator, logs streaming
|
||||
- **Reconnecting**: Yellow indicator, automatic retry in progress
|
||||
- **Disconnected**: Red indicator, manual reconnect available
|
||||
|
||||
### Troubleshooting Connection Issues
|
||||
|
||||
If the WebSocket disconnects frequently:
|
||||
|
||||
1. Check browser console for errors
|
||||
2. Verify no proxy is blocking WebSocket upgrades
|
||||
3. Ensure the Charon container has sufficient resources
|
||||
4. Check for network timeouts on long-idle connections
|
||||
|
||||
## Related
|
||||
|
||||
- [WebSocket Support](websocket.md)
|
||||
- [CrowdSec Integration](crowdsec.md)
|
||||
- [Back to Features](../features.md)
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
title: Smart Proxy Headers
|
||||
description: Automatic X-Real-IP, X-Forwarded-For, and X-Forwarded-Proto headers
|
||||
category: networking
|
||||
---
|
||||
|
||||
# Smart Proxy Headers
|
||||
@@ -9,16 +10,126 @@ Your backend applications need to know the real client IP address, not Charon's.
|
||||
|
||||
## Overview
|
||||
|
||||
<!-- TODO: Add detailed overview -->
|
||||
When traffic passes through a reverse proxy, your backend loses visibility into the original client connection. Without proxy headers, every request appears to come from Charon's IP address, breaking logging, rate limiting, geolocation, and security features.
|
||||
|
||||
Coming soon.
|
||||
### Standard Proxy Headers
|
||||
|
||||
| Header | Purpose | Example Value |
|
||||
|--------|---------|---------------|
|
||||
| **X-Real-IP** | Original client IP address | `203.0.113.42` |
|
||||
| **X-Forwarded-For** | Chain of proxy IPs | `203.0.113.42, 10.0.0.1` |
|
||||
| **X-Forwarded-Proto** | Original protocol (HTTP/HTTPS) | `https` |
|
||||
| **X-Forwarded-Host** | Original host header | `example.com` |
|
||||
| **X-Forwarded-Port** | Original port number | `443` |
|
||||
|
||||
## Why These Headers Matter
|
||||
|
||||
### Client IP Detection
|
||||
|
||||
Without X-Real-IP, your application sees Charon's internal IP for every request:
|
||||
|
||||
- **Logging**: All logs show the same IP, making debugging impossible
|
||||
- **Rate Limiting**: Cannot throttle abusive clients
|
||||
- **Geolocation**: Location services return proxy location, not user location
|
||||
- **Analytics**: Traffic analytics become meaningless
|
||||
|
||||
### HTTPS Enforcement
|
||||
|
||||
X-Forwarded-Proto tells your backend the original protocol:
|
||||
|
||||
- **Redirect Loops**: Backend sees HTTP, redirects to HTTPS, Charon proxies as HTTP, infinite loop
|
||||
- **Secure Cookies**: Applications need to know when to set `Secure` flag
|
||||
- **Mixed Content**: Helps applications generate correct absolute URLs
|
||||
|
||||
### Virtual Host Routing
|
||||
|
||||
X-Forwarded-Host preserves the original domain:
|
||||
|
||||
- **Multi-tenant Apps**: Route requests to correct tenant
|
||||
- **URL Generation**: Generate correct links in emails, redirects
|
||||
|
||||
## Configuration
|
||||
|
||||
<!-- TODO: Add configuration steps -->
|
||||
### Default Behavior
|
||||
|
||||
Coming soon.
|
||||
| Host Type | Proxy Headers |
|
||||
|-----------|---------------|
|
||||
| New hosts | **Enabled** by default |
|
||||
| Existing hosts (pre-upgrade) | **Disabled** (preserves existing behavior) |
|
||||
|
||||
### Enabling/Disabling
|
||||
|
||||
1. Navigate to **Hosts** → Select your host
|
||||
2. Go to **Advanced** tab
|
||||
3. Toggle **Proxy Headers** on or off
|
||||
4. Click **Save**
|
||||
|
||||
### Backend Configuration Requirements
|
||||
|
||||
Your backend must trust proxy headers from Charon. Common configurations:
|
||||
|
||||
**Node.js/Express:**
|
||||
```javascript
|
||||
app.set('trust proxy', true);
|
||||
```
|
||||
|
||||
**Django:**
|
||||
```python
|
||||
SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https')
|
||||
USE_X_FORWARDED_HOST = True
|
||||
```
|
||||
|
||||
**Rails:**
|
||||
```ruby
|
||||
config.action_dispatch.trusted_proxies = [IPAddr.new('10.0.0.0/8')]
|
||||
```
|
||||
|
||||
**PHP/Laravel:**
|
||||
```php
|
||||
// In TrustProxies middleware
|
||||
protected $proxies = '*';
|
||||
```
|
||||
|
||||
## When to Enable vs Disable
|
||||
|
||||
### Enable When
|
||||
|
||||
- Backend needs real client IP for logging or security
|
||||
- Application generates absolute URLs
|
||||
- Using secure cookies with HTTPS termination at proxy
|
||||
- Rate limiting or geolocation features are needed
|
||||
|
||||
### Disable When
|
||||
|
||||
- Backend is an external service you don't control
|
||||
- Proxying to another reverse proxy that handles headers
|
||||
- Legacy application that misinterprets forwarded headers
|
||||
- Security policy requires hiding internal topology
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Trusted Proxies
|
||||
|
||||
Only trust proxy headers from known sources. If your backend blindly trusts X-Forwarded-For, attackers can spoof their IP by injecting fake headers.
|
||||
|
||||
### Header Injection Prevention
|
||||
|
||||
Charon sanitizes incoming proxy headers before adding its own, preventing header injection attacks where malicious clients send fake forwarded headers.
|
||||
|
||||
### IP Chain Verification
|
||||
|
||||
When multiple proxies exist, verify the entire X-Forwarded-For chain rather than trusting only the first or last IP.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Issue | Likely Cause | Solution |
|
||||
|-------|--------------|----------|
|
||||
| Backend shows wrong IP | Headers not enabled | Enable proxy headers for host |
|
||||
| Redirect loop | Backend doesn't trust X-Forwarded-Proto | Configure backend trust settings |
|
||||
| Wrong URLs in emails | Missing X-Forwarded-Host trust | Enable host header forwarding |
|
||||
|
||||
## Related
|
||||
|
||||
- [Security Headers](security-headers.md) - Browser security headers
|
||||
- [SSL Certificates](ssl-certificates.md) - HTTPS configuration
|
||||
- [Back to Features](../features.md)
|
||||
|
||||
@@ -9,16 +9,105 @@ Prevent abuse by limiting how many requests a user or IP address can make. Stop
|
||||
|
||||
## Overview
|
||||
|
||||
<!-- TODO: Add detailed overview -->
|
||||
Rate limiting controls how frequently clients can make requests to your proxied services. When a client exceeds the configured limit, additional requests receive a `429 Too Many Requests` response until the limit resets.
|
||||
|
||||
Coming soon.
|
||||
Key concepts:
|
||||
|
||||
- **Requests per Second (RPS)** — Sustained request rate allowed
|
||||
- **Burst Limit** — Short-term spike allowance above RPS
|
||||
- **Time Window** — Period over which limits are calculated
|
||||
- **Per-IP Tracking** — Each client IP has independent limits
|
||||
|
||||
## Why Use This
|
||||
|
||||
- **Brute-Force Prevention** — Stop password guessing attacks
|
||||
- **API Protection** — Prevent excessive API consumption
|
||||
- **Resource Management** — Protect backend services from overload
|
||||
- **Fair Usage** — Ensure equitable access across all users
|
||||
- **Cost Control** — Limit expensive operations
|
||||
|
||||
## Configuration
|
||||
|
||||
<!-- TODO: Add configuration steps -->
|
||||
### Enabling Rate Limiting
|
||||
|
||||
Coming soon.
|
||||
1. Navigate to **Proxy Hosts**
|
||||
2. Edit or create a proxy host
|
||||
3. Go to the **Advanced** tab
|
||||
4. Toggle **Rate Limiting** to enabled
|
||||
5. Configure your limits
|
||||
|
||||
### Parameters
|
||||
|
||||
| Parameter | Description | Example |
|
||||
|-----------|-------------|---------|
|
||||
| **Requests/Second** | Sustained rate limit | `10` = 10 requests per second |
|
||||
| **Burst Limit** | Temporary spike allowance | `50` = allow 50 rapid requests |
|
||||
| **Time Window** | Reset period in seconds | `60` = limits reset every minute |
|
||||
|
||||
### Understanding Burst vs Sustained Rate
|
||||
|
||||
```text
|
||||
Sustained Rate: 10 req/sec
|
||||
Burst Limit: 50
|
||||
|
||||
Behavior:
|
||||
- Client can send 50 requests instantly (burst)
|
||||
- Then limited to 10 req/sec until burst refills
|
||||
- Burst tokens refill at the sustained rate
|
||||
```
|
||||
|
||||
This allows legitimate traffic spikes (page loads with many assets) while preventing sustained abuse.
|
||||
|
||||
### Recommended Configurations
|
||||
|
||||
| Use Case | RPS | Burst | Window |
|
||||
|----------|-----|-------|--------|
|
||||
| Public website | 20 | 100 | 60s |
|
||||
| Login endpoint | 5 | 10 | 60s |
|
||||
| API endpoint | 30 | 60 | 60s |
|
||||
| Static assets | 100 | 500 | 60s |
|
||||
|
||||
## Dashboard Integration
|
||||
|
||||
### Status Badge
|
||||
|
||||
When rate limiting is enabled, the proxy host displays a **Rate Limited** badge on:
|
||||
|
||||
- Proxy host list view
|
||||
- Host detail page
|
||||
|
||||
### Active Summary Card
|
||||
|
||||
The dashboard shows an **Active Rate Limiting** summary card displaying:
|
||||
|
||||
- Number of hosts with rate limiting enabled
|
||||
- Current configuration summary
|
||||
- Link to manage settings
|
||||
|
||||
## Response Headers
|
||||
|
||||
Rate-limited responses include helpful headers:
|
||||
|
||||
```http
|
||||
HTTP/1.1 429 Too Many Requests
|
||||
Retry-After: 5
|
||||
X-RateLimit-Limit: 10
|
||||
X-RateLimit-Remaining: 0
|
||||
X-RateLimit-Reset: 1642000000
|
||||
```
|
||||
|
||||
Clients can use these headers to implement backoff strategies.
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Start Generous** — Begin with higher limits and tighten based on observed traffic
|
||||
- **Monitor Logs** — Watch for legitimate users hitting limits
|
||||
- **Separate Endpoints** — Use different limits for different proxy hosts
|
||||
- **Combine with WAF** — Rate limiting + WAF provides layered protection
|
||||
|
||||
## Related
|
||||
|
||||
- [Access Control](./access-control.md) — IP-based access restrictions
|
||||
- [CrowdSec Integration](./crowdsec.md) — Automatic attacker blocking
|
||||
- [Proxy Hosts](./proxy-hosts.md) — Configure rate limits per host
|
||||
- [Back to Features](../features.md)
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
title: HTTP Security Headers
|
||||
description: Automatic security headers including CSP, HSTS, and more
|
||||
category: security
|
||||
---
|
||||
|
||||
# HTTP Security Headers
|
||||
@@ -9,16 +10,110 @@ Modern browsers expect specific security headers to protect your users. Charon a
|
||||
|
||||
## Overview
|
||||
|
||||
<!-- TODO: Add detailed overview -->
|
||||
HTTP security headers instruct browsers how to handle your content securely. Without them, your site remains vulnerable to clickjacking, XSS attacks, protocol downgrades, and MIME-type confusion. Charon provides a visual interface for configuring these headers without memorizing complex syntax.
|
||||
|
||||
Coming soon.
|
||||
### Supported Headers
|
||||
|
||||
| Header | Purpose |
|
||||
|--------|---------|
|
||||
| **HSTS** | Forces HTTPS connections, prevents downgrade attacks |
|
||||
| **Content-Security-Policy** | Controls resource loading, mitigates XSS |
|
||||
| **X-Frame-Options** | Prevents clickjacking via iframe embedding |
|
||||
| **X-Content-Type-Options** | Stops MIME-type sniffing attacks |
|
||||
| **Referrer-Policy** | Controls referrer information leakage |
|
||||
| **Permissions-Policy** | Restricts browser feature access (camera, mic, geolocation) |
|
||||
| **Cross-Origin-Opener-Policy** | Isolates browsing context |
|
||||
| **Cross-Origin-Resource-Policy** | Controls cross-origin resource sharing |
|
||||
|
||||
## Why Use This
|
||||
|
||||
- **Browser Protection**: Modern browsers actively check for security headers
|
||||
- **Compliance**: Many security audits and standards require specific headers
|
||||
- **Defense in Depth**: Headers add protection even if application code has vulnerabilities
|
||||
- **No Code Changes**: Protect legacy applications without modifying source code
|
||||
|
||||
## Security Presets
|
||||
|
||||
Charon offers three ready-to-use presets based on your security requirements:
|
||||
|
||||
### Basic (Production Safe)
|
||||
|
||||
Balanced security suitable for most production sites. Enables essential protections without breaking typical web functionality.
|
||||
|
||||
- HSTS enabled (1 year, includeSubdomains)
|
||||
- X-Frame-Options: SAMEORIGIN
|
||||
- X-Content-Type-Options: nosniff
|
||||
- Referrer-Policy: strict-origin-when-cross-origin
|
||||
|
||||
### Strict (High Security)
|
||||
|
||||
Enhanced security for applications handling sensitive data. May require CSP tuning for inline scripts.
|
||||
|
||||
- All Basic headers plus:
|
||||
- Content-Security-Policy with restrictive defaults
|
||||
- Permissions-Policy denying sensitive features
|
||||
- X-Frame-Options: DENY
|
||||
|
||||
### Paranoid (Maximum)
|
||||
|
||||
Maximum security for high-value targets. Expect to customize CSP directives for your specific application.
|
||||
|
||||
- All Strict headers plus:
|
||||
- CSP with nonce-based script execution
|
||||
- Cross-Origin policies fully restricted
|
||||
- All permissions denied by default
|
||||
|
||||
## Configuration
|
||||
|
||||
<!-- TODO: Add configuration steps -->
|
||||
### Using Presets
|
||||
|
||||
Coming soon.
|
||||
1. Navigate to **Hosts** → Select your host → **Security Headers**
|
||||
2. Choose a preset from the dropdown
|
||||
3. Review the applied headers in the preview
|
||||
4. Click **Save** to apply
|
||||
|
||||
### Custom Header Profiles
|
||||
|
||||
Create reusable header configurations:
|
||||
|
||||
1. Go to **Settings** → **Security Profiles**
|
||||
2. Click **Create Profile**
|
||||
3. Name your profile (e.g., "API Servers", "Public Sites")
|
||||
4. Configure individual headers
|
||||
5. Save and apply to multiple hosts
|
||||
|
||||
### Interactive CSP Builder
|
||||
|
||||
The CSP Builder provides a visual interface for constructing Content-Security-Policy:
|
||||
|
||||
1. Select directive (script-src, style-src, img-src, etc.)
|
||||
2. Add allowed sources (self, specific domains, unsafe-inline)
|
||||
3. Preview the generated policy
|
||||
4. Test against your site before applying
|
||||
|
||||
## Security Score Calculator
|
||||
|
||||
Each host displays a security score from 0-100 based on enabled headers:
|
||||
|
||||
| Score Range | Rating | Description |
|
||||
|-------------|--------|-------------|
|
||||
| 90-100 | Excellent | All recommended headers configured |
|
||||
| 70-89 | Good | Core protections in place |
|
||||
| 50-69 | Fair | Basic headers only |
|
||||
| 0-49 | Poor | Missing critical headers |
|
||||
|
||||
## When to Use Each Preset
|
||||
|
||||
| Scenario | Recommended Preset |
|
||||
|----------|-------------------|
|
||||
| Marketing sites, blogs | Basic |
|
||||
| E-commerce, user accounts | Strict |
|
||||
| Banking, healthcare, government | Paranoid |
|
||||
| Internal tools | Basic or Strict |
|
||||
| APIs (no browser UI) | Minimal or disabled |
|
||||
|
||||
## Related
|
||||
|
||||
- [Proxy Headers](proxy-headers.md) - Backend communication headers
|
||||
- [Access Lists](access-lists.md) - IP-based access control
|
||||
- [Back to Features](../features.md)
|
||||
|
||||
@@ -9,16 +9,69 @@ Charon automatically obtains free SSL certificates from Let's Encrypt or ZeroSSL
|
||||
|
||||
## Overview
|
||||
|
||||
<!-- TODO: Add detailed overview -->
|
||||
When you create a proxy host with HTTPS enabled, Charon handles the entire certificate lifecycle:
|
||||
|
||||
Coming soon.
|
||||
1. **Automatic Provisioning** — Requests a certificate from your chosen provider
|
||||
2. **Domain Validation** — Completes the ACME challenge automatically
|
||||
3. **Installation** — Configures Caddy to use the new certificate
|
||||
4. **Renewal** — Renews certificates before they expire (typically 30 days before)
|
||||
5. **Smart Cleanup** — Removes certificates when you delete hosts
|
||||
|
||||
## Configuration
|
||||
## Why Use This
|
||||
|
||||
<!-- TODO: Add configuration steps -->
|
||||
- **Zero Configuration** — Works out of the box with sensible defaults
|
||||
- **Free Certificates** — Both Let's Encrypt and ZeroSSL provide certificates at no cost
|
||||
- **Always Valid** — Automatic renewal prevents certificate expiration
|
||||
- **No Downtime** — Certificate updates happen seamlessly
|
||||
|
||||
Coming soon.
|
||||
## SSL Provider Selection
|
||||
|
||||
Navigate to **Settings → Default Settings** to choose your SSL provider:
|
||||
|
||||
| Provider | Best For | Rate Limits |
|
||||
|----------|----------|-------------|
|
||||
| **Auto** | Most users | Caddy selects automatically |
|
||||
| **Let's Encrypt (Production)** | Production sites | 50 certs/domain/week |
|
||||
| **Let's Encrypt (Staging)** | Testing & development | Unlimited (untrusted certs) |
|
||||
| **ZeroSSL** | Alternative to LE, or if rate-limited | 3 certs/domain/90 days (free tier) |
|
||||
|
||||
### When to Use Each Provider
|
||||
|
||||
- **Auto**: Recommended for most users. Caddy intelligently selects the best provider.
|
||||
- **Let's Encrypt Production**: When you need trusted certificates and are within rate limits.
|
||||
- **Let's Encrypt Staging**: When testing your setup—certificates are not trusted by browsers but have no rate limits.
|
||||
- **ZeroSSL**: When you've hit Let's Encrypt rate limits or prefer an alternative CA.
|
||||
|
||||
## Dashboard Certificate Status
|
||||
|
||||
The **Certificate Status Card** on your dashboard shows:
|
||||
|
||||
- Total certificates managed
|
||||
- Certificates expiring soon (within 30 days)
|
||||
- Any failed certificate requests
|
||||
|
||||
Click on any certificate to view details including expiration date, domains covered, and issuer information.
|
||||
|
||||
## Smart Certificate Cleanup
|
||||
|
||||
When you delete a proxy host, Charon automatically:
|
||||
|
||||
1. Removes the certificate from Caddy's configuration
|
||||
2. Cleans up any associated ACME data
|
||||
3. Frees up rate limit quota for new certificates
|
||||
|
||||
This prevents certificate accumulation and keeps your system tidy.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Issue | Solution |
|
||||
|-------|----------|
|
||||
| Certificate not issued | Ensure ports 80/443 are accessible from the internet |
|
||||
| Rate limit exceeded | Switch to Let's Encrypt Staging or ZeroSSL temporarily |
|
||||
| Domain validation failed | Verify DNS points to your Charon server |
|
||||
|
||||
## Related
|
||||
|
||||
- [Proxy Hosts](./proxy-hosts.md) — Configure HTTPS for your services
|
||||
- [DNS Providers](./dns-providers.md) — Use DNS challenge for wildcard certificates
|
||||
- [Back to Features](../features.md)
|
||||
|
||||
@@ -9,16 +9,140 @@ Know exactly what you're running. Every Charon release includes cryptographic si
|
||||
|
||||
## Overview
|
||||
|
||||
<!-- TODO: Add detailed overview -->
|
||||
Supply chain attacks are increasingly common. Charon protects you with multiple verification layers that prove the image you're running was built from the official source code, hasn't been tampered with, and contains no hidden dependencies.
|
||||
|
||||
Coming soon.
|
||||
### Security Artifacts
|
||||
|
||||
## Configuration
|
||||
| Artifact | Purpose | Standard |
|
||||
|----------|---------|----------|
|
||||
| **Cosign Signature** | Cryptographic proof of origin | Sigstore |
|
||||
| **SLSA Provenance** | Build process attestation | SLSA Level 3 |
|
||||
| **SBOM** | Complete dependency inventory | SPDX/CycloneDX |
|
||||
|
||||
<!-- TODO: Add configuration steps -->
|
||||
## Why Supply Chain Security Matters
|
||||
|
||||
Coming soon.
|
||||
| Threat | Mitigation |
|
||||
|--------|------------|
|
||||
| **Compromised CI/CD** | SLSA provenance verifies build source |
|
||||
| **Malicious maintainer** | Signatures require private key access |
|
||||
| **Dependency hijacking** | SBOM enables vulnerability scanning |
|
||||
| **Registry tampering** | Signatures detect unauthorized changes |
|
||||
| **Audit requirements** | Complete traceability for compliance |
|
||||
|
||||
## Verifying Image Signatures
|
||||
|
||||
### Prerequisites
|
||||
|
||||
```bash
|
||||
# Install Cosign
|
||||
# macOS
|
||||
brew install cosign
|
||||
|
||||
# Linux
|
||||
curl -LO https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64
|
||||
chmod +x cosign-linux-amd64 && sudo mv cosign-linux-amd64 /usr/local/bin/cosign
|
||||
```
|
||||
|
||||
### Verify a Charon Image
|
||||
|
||||
```bash
|
||||
# Verify signature (keyless - uses Sigstore public transparency log)
|
||||
cosign verify ghcr.io/wikid82/charon:latest \
|
||||
--certificate-identity-regexp='https://github.com/Wikid82/charon/.*' \
|
||||
--certificate-oidc-issuer='https://token.actions.githubusercontent.com'
|
||||
|
||||
# Successful output shows:
|
||||
# Verification for ghcr.io/wikid82/charon:latest --
|
||||
# The following checks were performed on each of these signatures:
|
||||
# - The cosign claims were validated
|
||||
# - The signatures were verified against the specified public key
|
||||
```
|
||||
|
||||
### Verify SLSA Provenance
|
||||
|
||||
```bash
|
||||
# Install slsa-verifier
|
||||
go install github.com/slsa-framework/slsa-verifier/v2/cli/slsa-verifier@latest
|
||||
|
||||
# Verify provenance attestation
|
||||
slsa-verifier verify-image ghcr.io/wikid82/charon:latest \
|
||||
--source-uri github.com/Wikid82/charon \
|
||||
--source-tag v2.0.0
|
||||
```
|
||||
|
||||
## Software Bill of Materials (SBOM)
|
||||
|
||||
### What's Included
|
||||
|
||||
The SBOM lists every component in the image:
|
||||
|
||||
- Go modules and versions
|
||||
- System packages (Alpine)
|
||||
- Frontend npm dependencies
|
||||
- Build tools used
|
||||
|
||||
### Retrieving the SBOM
|
||||
|
||||
```bash
|
||||
# Download SBOM attestation
|
||||
cosign download sbom ghcr.io/wikid82/charon:latest > charon-sbom.spdx.json
|
||||
|
||||
# View in human-readable format
|
||||
cat charon-sbom.spdx.json | jq '.packages[] | {name, version}'
|
||||
```
|
||||
|
||||
### Vulnerability Scanning
|
||||
|
||||
Use the SBOM with vulnerability scanners:
|
||||
|
||||
```bash
|
||||
# Scan with Trivy
|
||||
trivy sbom charon-sbom.spdx.json
|
||||
|
||||
# Scan with Grype
|
||||
grype sbom:charon-sbom.spdx.json
|
||||
```
|
||||
|
||||
## SLSA Provenance Details
|
||||
|
||||
SLSA (Supply-chain Levels for Software Artifacts) provenance includes:
|
||||
|
||||
| Field | Content |
|
||||
|-------|---------|
|
||||
| `buildType` | GitHub Actions workflow |
|
||||
| `invocation` | Commit SHA, branch, workflow run |
|
||||
| `materials` | Source repository, dependencies |
|
||||
| `builder` | GitHub-hosted runner details |
|
||||
|
||||
### Example Provenance
|
||||
|
||||
```json
|
||||
{
|
||||
"buildType": "https://github.com/slsa-framework/slsa-github-generator",
|
||||
"invocation": {
|
||||
"configSource": {
|
||||
"uri": "git+https://github.com/Wikid82/charon@refs/tags/v2.0.0",
|
||||
"entryPoint": ".github/workflows/release.yml"
|
||||
}
|
||||
},
|
||||
"materials": [{
|
||||
"uri": "git+https://github.com/Wikid82/charon",
|
||||
"digest": {"sha1": "abc123..."}
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
## Enterprise Compliance
|
||||
|
||||
These artifacts support compliance requirements:
|
||||
|
||||
- **SOC 2**: Demonstrates secure build practices
|
||||
- **FedRAMP**: Provides software supply chain documentation
|
||||
- **PCI DSS**: Enables change management auditing
|
||||
- **NIST SSDF**: Aligns with secure development framework
|
||||
|
||||
## Related
|
||||
|
||||
- [Security Hardening](security-hardening.md) - Runtime security features
|
||||
- [Coraza WAF](coraza-waf.md) - Application firewall
|
||||
- [Back to Features](../features.md)
|
||||
|
||||
@@ -9,16 +9,109 @@ Easy on the eyes, day or night. Toggle between light and dark themes to match yo
|
||||
|
||||
## Overview
|
||||
|
||||
<!-- TODO: Add detailed overview -->
|
||||
Charon's interface is built with **Tailwind CSS v4** and a modern React component library. Dark mode is the default, with automatic system preference detection and manual override support.
|
||||
|
||||
Coming soon.
|
||||
### Design Philosophy
|
||||
|
||||
## Configuration
|
||||
- **Dark-first**: Optimized for low-light environments and reduced eye strain
|
||||
- **Semantic colors**: Consistent meaning across light and dark modes
|
||||
- **Accessibility-first**: WCAG 2.1 AA compliant with focus management
|
||||
- **Responsive**: Works seamlessly on desktop, tablet, and mobile
|
||||
|
||||
<!-- TODO: Add configuration steps -->
|
||||
## Why a Modern UI Matters
|
||||
|
||||
Coming soon.
|
||||
| Feature | Benefit |
|
||||
|---------|---------|
|
||||
| **Dark Mode** | Reduced eye strain during long sessions |
|
||||
| **Semantic Tokens** | Consistent, predictable color behavior |
|
||||
| **Component Library** | Professional, polished interactions |
|
||||
| **Keyboard Navigation** | Full functionality without a mouse |
|
||||
| **Screen Reader Support** | Accessible to all users |
|
||||
|
||||
## Theme System
|
||||
|
||||
### Color Tokens
|
||||
|
||||
Charon uses semantic color tokens that automatically adapt:
|
||||
|
||||
| Token | Light Mode | Dark Mode | Usage |
|
||||
|-------|------------|-----------|-------|
|
||||
| `--background` | White | Slate 950 | Page backgrounds |
|
||||
| `--foreground` | Slate 900 | Slate 50 | Primary text |
|
||||
| `--primary` | Blue 600 | Blue 500 | Actions, links |
|
||||
| `--destructive` | Red 600 | Red 500 | Delete, errors |
|
||||
| `--muted` | Slate 100 | Slate 800 | Secondary surfaces |
|
||||
| `--border` | Slate 200 | Slate 700 | Dividers, outlines |
|
||||
|
||||
### Switching Themes
|
||||
|
||||
1. Click the **theme toggle** in the top navigation
|
||||
2. Choose: **Light**, **Dark**, or **System**
|
||||
3. Preference is saved to local storage
|
||||
|
||||
## Component Library
|
||||
|
||||
### Core Components
|
||||
|
||||
| Component | Purpose | Accessibility |
|
||||
|-----------|---------|---------------|
|
||||
| **Badge** | Status indicators, tags | Color + icon redundancy |
|
||||
| **Alert** | Notifications, warnings | ARIA live regions |
|
||||
| **Dialog** | Modal interactions | Focus trap, ESC to close |
|
||||
| **DataTable** | Sortable data display | Keyboard navigation |
|
||||
| **Tooltip** | Contextual help | Delay for screen readers |
|
||||
| **DropdownMenu** | Action menus | Arrow key navigation |
|
||||
|
||||
### Status Indicators
|
||||
|
||||
Visual status uses color AND icons for accessibility:
|
||||
|
||||
- ✅ **Online** - Green badge with check icon
|
||||
- ⚠️ **Warning** - Yellow badge with alert icon
|
||||
- ❌ **Offline** - Red badge with X icon
|
||||
- ⏳ **Pending** - Gray badge with clock icon
|
||||
|
||||
## Accessibility Features
|
||||
|
||||
### WCAG 2.1 Compliance
|
||||
|
||||
- **Color contrast**: Minimum 4.5:1 for text, 3:1 for UI elements
|
||||
- **Focus indicators**: Visible focus rings on all interactive elements
|
||||
- **Text scaling**: UI adapts to browser zoom up to 200%
|
||||
- **Motion**: Respects `prefers-reduced-motion`
|
||||
|
||||
### Keyboard Navigation
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `Tab` | Move between interactive elements |
|
||||
| `Enter` / `Space` | Activate buttons, links |
|
||||
| `Escape` | Close dialogs, dropdowns |
|
||||
| `Arrow keys` | Navigate within menus, tables |
|
||||
|
||||
### Screen Reader Support
|
||||
|
||||
- Semantic HTML structure with landmarks
|
||||
- ARIA labels on icon-only buttons
|
||||
- Live regions for dynamic content updates
|
||||
- Skip links for main content access
|
||||
|
||||
## Customization
|
||||
|
||||
### CSS Variables Override
|
||||
|
||||
Advanced users can customize the theme via CSS:
|
||||
|
||||
```css
|
||||
/* Custom brand colors */
|
||||
:root {
|
||||
--primary: 210 100% 50%; /* Custom blue */
|
||||
--radius: 0.75rem; /* Rounder corners */
|
||||
}
|
||||
```
|
||||
|
||||
## Related
|
||||
|
||||
- [Notifications](notifications.md) - Visual notification system
|
||||
- [REST API](api.md) - Programmatic access
|
||||
- [Back to Features](../features.md)
|
||||
|
||||
@@ -9,16 +9,82 @@ Stop common attacks like SQL injection, cross-site scripting (XSS), and path tra
|
||||
|
||||
## Overview
|
||||
|
||||
<!-- TODO: Add detailed overview -->
|
||||
The Web Application Firewall inspects every HTTP/HTTPS request and blocks malicious payloads before they reach your backend services. Charon uses [Coraza](https://coraza.io/), a high-performance, open-source WAF engine compatible with the OWASP Core Rule Set (CRS).
|
||||
|
||||
Coming soon.
|
||||
Protected attack types include:
|
||||
|
||||
- **SQL Injection** — Blocks database manipulation attempts
|
||||
- **Cross-Site Scripting (XSS)** — Prevents script injection attacks
|
||||
- **Path Traversal** — Stops directory traversal exploits
|
||||
- **Remote Code Execution** — Blocks command injection
|
||||
- **Zero-Day Exploits** — CRS updates provide protection against newly discovered vulnerabilities
|
||||
|
||||
## Why Use This
|
||||
|
||||
- **Defense in Depth** — Add a security layer in front of your applications
|
||||
- **OWASP CRS** — Industry-standard ruleset trusted by enterprises
|
||||
- **Low Latency** — Coraza processes rules efficiently with minimal overhead
|
||||
- **Flexible Modes** — Choose between monitoring and active blocking
|
||||
|
||||
## Configuration
|
||||
|
||||
<!-- TODO: Add configuration steps -->
|
||||
### Enabling WAF
|
||||
|
||||
Coming soon.
|
||||
1. Navigate to **Proxy Hosts**
|
||||
2. Edit or create a proxy host
|
||||
3. In the **Security** tab, toggle **Web Application Firewall**
|
||||
4. Select your preferred mode
|
||||
|
||||
### Operating Modes
|
||||
|
||||
| Mode | Behavior | Use Case |
|
||||
|------|----------|----------|
|
||||
| **Monitor** | Logs threats but allows traffic | Testing rules, reducing false positives |
|
||||
| **Block** | Actively blocks malicious requests | Production protection |
|
||||
|
||||
**Recommendation**: Start in Monitor mode to review detected threats, then switch to Block mode once you're confident in the rules.
|
||||
|
||||
### Per-Host Configuration
|
||||
|
||||
WAF can be enabled independently for each proxy host:
|
||||
|
||||
- Enable for public-facing applications
|
||||
- Disable for internal services or APIs with custom security
|
||||
- Mix modes across different hosts as needed
|
||||
|
||||
## Zero-Day Protection
|
||||
|
||||
The OWASP Core Rule Set is regularly updated to address:
|
||||
|
||||
- Newly discovered CVEs
|
||||
- Emerging attack patterns
|
||||
- Bypass techniques
|
||||
|
||||
Charon includes the latest CRS version and receives updates through container image releases.
|
||||
|
||||
## Limitations
|
||||
|
||||
The WAF protects **HTTP and HTTPS traffic only**:
|
||||
|
||||
| Traffic Type | Protected |
|
||||
|--------------|-----------|
|
||||
| HTTP/HTTPS Proxy Hosts | ✅ Yes |
|
||||
| TCP/UDP Streams | ❌ No |
|
||||
| Non-HTTP protocols | ❌ No |
|
||||
|
||||
For TCP/UDP protection, use [CrowdSec](./crowdsec.md) or network-level firewalls.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Issue | Solution |
|
||||
|-------|----------|
|
||||
| Legitimate requests blocked | Switch to Monitor mode and review logs |
|
||||
| High latency | Check if complex rules are triggering; consider rule tuning |
|
||||
| WAF not activating | Verify the proxy host has WAF enabled in Security tab |
|
||||
|
||||
## Related
|
||||
|
||||
- [CrowdSec Integration](./crowdsec.md) — Behavioral threat detection
|
||||
- [Access Control](./access-control.md) — IP and geo-based restrictions
|
||||
- [Proxy Hosts](./proxy-hosts.md) — Configure WAF per host
|
||||
- [Back to Features](../features.md)
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
title: Point & Click Management
|
||||
description: Manage your reverse proxy through an intuitive web interface
|
||||
category: core
|
||||
---
|
||||
|
||||
# Point & Click Management
|
||||
@@ -9,16 +10,120 @@ Say goodbye to editing configuration files and memorizing commands. Charon gives
|
||||
|
||||
## Overview
|
||||
|
||||
<!-- TODO: Add detailed overview with screenshots -->
|
||||
Traditional reverse proxy configuration requires editing text files, understanding complex syntax, and reloading services. Charon replaces this workflow with an intuitive web interface that makes proxy management accessible to everyone.
|
||||
|
||||
Coming soon.
|
||||
### Key Capabilities
|
||||
|
||||
- **Form-Based Configuration**: Fill in fields instead of writing syntax
|
||||
- **Instant Validation**: Catch errors before they break your setup
|
||||
- **Live Preview**: See configuration changes before applying
|
||||
- **One-Click Actions**: Enable, disable, or delete hosts instantly
|
||||
|
||||
## Why Use This
|
||||
|
||||
### No Config Files Needed
|
||||
|
||||
- Never edit Caddyfile, nginx.conf, or Apache configs manually
|
||||
- Changes apply immediately without service restarts
|
||||
- Syntax errors become impossible—the UI validates everything
|
||||
|
||||
### Reduced Learning Curve
|
||||
|
||||
- New team members are productive in minutes
|
||||
- No need to memorize directives or options
|
||||
- Tooltips explain each setting's purpose
|
||||
|
||||
### Audit Trail
|
||||
|
||||
- See who changed what and when
|
||||
- Roll back to previous configurations
|
||||
- Track configuration drift over time
|
||||
|
||||
## Features
|
||||
|
||||
### Form-Based Host Creation
|
||||
|
||||
Creating a new proxy host takes seconds:
|
||||
|
||||
1. Click **Add Host**
|
||||
2. Enter domain name (e.g., `app.example.com`)
|
||||
3. Enter backend address (e.g., `http://192.168.1.100:3000`)
|
||||
4. Toggle SSL certificate option
|
||||
5. Click **Save**
|
||||
|
||||
### Bulk Operations
|
||||
|
||||
Manage multiple hosts efficiently:
|
||||
|
||||
- **Bulk Enable/Disable**: Select hosts and toggle status
|
||||
- **Bulk Delete**: Remove multiple hosts at once
|
||||
- **Bulk Export**: Download configurations for backup
|
||||
- **Clone Host**: Duplicate configuration to new domain
|
||||
|
||||
### Search and Filter
|
||||
|
||||
Find hosts quickly in large deployments:
|
||||
|
||||
- Search by domain name
|
||||
- Filter by status (enabled, disabled, error)
|
||||
- Filter by certificate status
|
||||
- Sort by name, creation date, or last modified
|
||||
|
||||
## Mobile-Friendly Design
|
||||
|
||||
Charon's responsive interface works on any device:
|
||||
|
||||
- **Phone**: Manage proxies from anywhere
|
||||
- **Tablet**: Full functionality with touch-friendly controls
|
||||
- **Desktop**: Complete dashboard with side-by-side panels
|
||||
|
||||
### Dark Mode Interface
|
||||
|
||||
Reduce eye strain during late-night maintenance:
|
||||
|
||||
- Automatic detection of system preference
|
||||
- Manual toggle in settings
|
||||
- High contrast for accessibility
|
||||
- Consistent styling across all components
|
||||
|
||||
## Configuration
|
||||
|
||||
<!-- TODO: Add configuration steps -->
|
||||
### Accessing the UI
|
||||
|
||||
Coming soon.
|
||||
1. Open your browser to Charon's address (default: `http://localhost:81`)
|
||||
2. Log in with your credentials
|
||||
3. Dashboard displays all configured hosts
|
||||
|
||||
### Quick Actions
|
||||
|
||||
| Action | How To |
|
||||
|--------|--------|
|
||||
| Add new host | Click **+ Add Host** button |
|
||||
| Edit host | Click host row or edit icon |
|
||||
| Enable/Disable | Toggle switch in host row |
|
||||
| Delete host | Click delete icon, confirm |
|
||||
| View logs | Click host → **Logs** tab |
|
||||
|
||||
### Keyboard Shortcuts
|
||||
|
||||
| Shortcut | Action |
|
||||
|----------|--------|
|
||||
| `Ctrl/Cmd + N` | New host |
|
||||
| `Ctrl/Cmd + S` | Save current form |
|
||||
| `Ctrl/Cmd + F` | Focus search |
|
||||
| `Escape` | Close modal/cancel |
|
||||
|
||||
## Dashboard Overview
|
||||
|
||||
The main dashboard provides at-a-glance status:
|
||||
|
||||
- **Total Hosts**: Number of configured proxies
|
||||
- **Active/Inactive**: Hosts currently serving traffic
|
||||
- **Certificate Status**: SSL expiration warnings
|
||||
- **Recent Activity**: Latest configuration changes
|
||||
|
||||
## Related
|
||||
|
||||
- [Docker Integration](docker-integration.md) - Auto-discover containers
|
||||
- [Caddyfile Import](caddyfile-import.md) - Migrate existing configs
|
||||
- [Back to Features](../features.md)
|
||||
|
||||
@@ -9,16 +9,69 @@ Real-time applications like chat servers, live dashboards, and collaborative too
|
||||
|
||||
## Overview
|
||||
|
||||
<!-- TODO: Add detailed overview -->
|
||||
WebSocket connections enable persistent, bidirectional communication between browsers and servers. Unlike traditional HTTP requests, WebSockets maintain an open connection for real-time data exchange.
|
||||
|
||||
Coming soon.
|
||||
Charon automatically detects and handles WebSocket upgrade requests, proxying them to your backend services transparently. This works for any application that uses WebSockets—no special configuration required.
|
||||
|
||||
## Why Use This
|
||||
|
||||
- **Zero Configuration**: WebSocket proxying works automatically
|
||||
- **Full Protocol Support**: Handles all WebSocket features including subprotocols
|
||||
- **Transparent Proxying**: Your applications don't know they're behind a proxy
|
||||
- **TLS Termination**: Secure WebSocket (wss://) connections handled automatically
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
WebSocket support enables proxying for:
|
||||
|
||||
| Application Type | Examples |
|
||||
|-----------------|----------|
|
||||
| **Chat Applications** | Slack alternatives, support chat widgets |
|
||||
| **Live Dashboards** | Monitoring tools, analytics platforms |
|
||||
| **Collaborative Tools** | Real-time document editing, whiteboards |
|
||||
| **Gaming** | Multiplayer game servers, matchmaking |
|
||||
| **Notifications** | Push notifications, live alerts |
|
||||
| **Streaming** | Live data feeds, stock tickers |
|
||||
|
||||
## How It Works
|
||||
|
||||
When Caddy receives a request with WebSocket upgrade headers:
|
||||
|
||||
1. Caddy detects the `Upgrade: websocket` header
|
||||
2. The connection is upgraded from HTTP to WebSocket
|
||||
3. Traffic flows bidirectionally through the proxy
|
||||
4. Connection remains open until either side closes it
|
||||
|
||||
### Technical Details
|
||||
|
||||
Caddy handles these WebSocket aspects automatically:
|
||||
|
||||
- **Connection Upgrade**: Properly forwards upgrade headers
|
||||
- **Protocol Negotiation**: Passes through subprotocol selection
|
||||
- **Keep-Alive**: Maintains connection through proxy timeouts
|
||||
- **Graceful Close**: Handles WebSocket close frames correctly
|
||||
|
||||
## Configuration
|
||||
|
||||
<!-- TODO: Add configuration steps -->
|
||||
No configuration is needed. Simply create a proxy host pointing to your WebSocket-enabled backend:
|
||||
|
||||
Coming soon.
|
||||
```text
|
||||
Backend: http://your-app:3000
|
||||
```
|
||||
|
||||
Your application's WebSocket connections (both `ws://` and `wss://`) will work automatically.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If WebSocket connections fail:
|
||||
|
||||
1. **Check Backend**: Ensure your app listens for WebSocket connections
|
||||
2. **Verify Port**: WebSocket uses the same port as HTTP
|
||||
3. **Test Directly**: Try connecting to the backend without the proxy
|
||||
4. **Check Logs**: Look for connection errors in real-time logs
|
||||
|
||||
## Related
|
||||
|
||||
- [Real-Time Logs](logs.md)
|
||||
- [Proxy Hosts](proxy-hosts.md)
|
||||
- [Back to Features](../features.md)
|
||||
|
||||
Reference in New Issue
Block a user