943 lines
30 KiB
Markdown
943 lines
30 KiB
Markdown
# @serve.zone/dcrouter
|
|
|
|
|
|
|
|
**dcrouter: The all-in-one gateway for your datacenter.** 🚀
|
|
|
|
A comprehensive traffic routing solution that provides unified gateway capabilities for HTTP/HTTPS, TCP/SNI, email (SMTP), DNS, and RADIUS protocols. Designed for enterprises requiring robust traffic management, automatic TLS certificate provisioning, and enterprise-grade email infrastructure — all from a single process.
|
|
|
|
## Issue Reporting and Security
|
|
|
|
For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
|
|
|
|
## Table of Contents
|
|
|
|
- [Features](#features)
|
|
- [Installation](#installation)
|
|
- [Quick Start](#quick-start)
|
|
- [Architecture](#architecture)
|
|
- [Configuration Reference](#configuration-reference)
|
|
- [HTTP/HTTPS & TCP/SNI Routing](#httphttps--tcpsni-routing)
|
|
- [Email System](#email-system)
|
|
- [DNS Server](#dns-server)
|
|
- [RADIUS Server](#radius-server)
|
|
- [Storage & Caching](#storage--caching)
|
|
- [Security Features](#security-features)
|
|
- [OpsServer Dashboard](#opsserver-dashboard)
|
|
- [API Reference](#api-reference)
|
|
- [Sub-Modules](#sub-modules)
|
|
- [Testing](#testing)
|
|
- [License and Legal Information](#license-and-legal-information)
|
|
|
|
## Features
|
|
|
|
### 🌐 Universal Traffic Router
|
|
- **HTTP/HTTPS routing** with domain matching, path-based forwarding, and automatic TLS
|
|
- **TCP/SNI proxy** for any protocol with TLS termination or passthrough
|
|
- **DNS server** with authoritative zones, dynamic record management, and DNS-over-HTTPS
|
|
- **Multi-protocol support** on the same infrastructure via [SmartProxy](https://code.foss.global/push.rocks/smartproxy)
|
|
|
|
### 📧 Complete Email Infrastructure
|
|
- **Multi-domain SMTP server** on standard ports (25, 587, 465)
|
|
- **Pattern-based email routing** with four action types: forward, process, deliver, reject
|
|
- **DKIM signing & verification**, SPF, DMARC authentication stack
|
|
- **Enterprise deliverability** with IP warmup schedules and sender reputation tracking
|
|
- **Bounce handling** with automatic suppression lists
|
|
- **Hierarchical rate limiting** — global, per-domain, per-sender
|
|
|
|
### 🔒 Enterprise Security
|
|
- **Automatic TLS certificates** via ACME with Cloudflare DNS-01 challenges
|
|
- **IP reputation checking** with caching and configurable thresholds
|
|
- **Content scanning** for spam, viruses, and malicious attachments
|
|
- **Security event logging** with structured audit trails
|
|
|
|
### 📡 RADIUS Server
|
|
- **MAC Authentication Bypass (MAB)** for network device authentication
|
|
- **VLAN assignment** based on exact MAC, OUI prefix, or wildcard patterns
|
|
- **RADIUS accounting** for session tracking, traffic metering, and billing
|
|
- **Real-time management** via OpsServer API
|
|
|
|
### ⚡ High Performance
|
|
- **Rust-powered proxy engine** via SmartProxy for maximum throughput
|
|
- **Connection pooling** for outbound SMTP and backend services
|
|
- **Socket-handler mode** — direct socket passing eliminates internal port hops
|
|
- **Real-time metrics** via SmartMetrics (CPU, memory, connections, throughput)
|
|
|
|
### 💾 Persistent Storage & Caching
|
|
- **Multiple storage backends**: filesystem, custom functions, or in-memory
|
|
- **Embedded cache database** via smartdata + TsmDb (MongoDB-compatible)
|
|
- **Automatic TTL-based cleanup** for cached emails, IP reputation, DKIM keys, and more
|
|
|
|
### 🖥️ OpsServer Dashboard
|
|
- **Web-based management interface** with real-time monitoring
|
|
- **JWT authentication** with session persistence
|
|
- **Live views** for connections, email queues, DNS queries, RADIUS sessions, and security events
|
|
- **Read-only configuration display** — DcRouter is configured through code
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
pnpm add @serve.zone/dcrouter
|
|
# or
|
|
npm install @serve.zone/dcrouter
|
|
```
|
|
|
|
### Prerequisites
|
|
|
|
- **Node.js 18+** with ES module support
|
|
- Valid domain with DNS control (for ACME certificate automation)
|
|
- Cloudflare API token (for DNS-01 challenges) — optional
|
|
|
|
## Quick Start
|
|
|
|
### Basic HTTP/HTTPS Router
|
|
|
|
```typescript
|
|
import { DcRouter } from '@serve.zone/dcrouter';
|
|
|
|
const router = new DcRouter({
|
|
smartProxyConfig: {
|
|
routes: [
|
|
{
|
|
name: 'web-app',
|
|
match: { domains: ['example.com', 'www.example.com'], ports: [443] },
|
|
action: {
|
|
type: 'forward',
|
|
targets: [{ host: '192.168.1.10', port: 8080 }],
|
|
tls: { mode: 'terminate', certificate: 'auto' }
|
|
}
|
|
}
|
|
],
|
|
acme: {
|
|
email: 'admin@example.com',
|
|
enabled: true,
|
|
useProduction: true
|
|
}
|
|
}
|
|
});
|
|
|
|
await router.start();
|
|
```
|
|
|
|
### Basic Email Server
|
|
|
|
```typescript
|
|
import { DcRouter } from '@serve.zone/dcrouter';
|
|
|
|
const router = new DcRouter({
|
|
emailConfig: {
|
|
ports: [25, 587, 465],
|
|
hostname: 'mail.example.com',
|
|
domains: [
|
|
{
|
|
domain: 'example.com',
|
|
dnsMode: 'external-dns'
|
|
}
|
|
],
|
|
routes: [
|
|
{
|
|
name: 'process-all',
|
|
match: { recipients: '*@example.com' },
|
|
action: {
|
|
type: 'process',
|
|
process: { scan: true, dkim: true, queue: 'normal' }
|
|
}
|
|
}
|
|
]
|
|
}
|
|
});
|
|
|
|
await router.start();
|
|
```
|
|
|
|
### Full Stack with Dashboard
|
|
|
|
```typescript
|
|
import { DcRouter } from '@serve.zone/dcrouter';
|
|
|
|
const router = new DcRouter({
|
|
// HTTP/HTTPS routing
|
|
smartProxyConfig: {
|
|
routes: [
|
|
{
|
|
name: 'website',
|
|
match: { domains: ['example.com'], ports: [443] },
|
|
action: {
|
|
type: 'forward',
|
|
targets: [{ host: '192.168.1.10', port: 80 }],
|
|
tls: { mode: 'terminate', certificate: 'auto' }
|
|
}
|
|
}
|
|
],
|
|
acme: { email: 'ssl@example.com', enabled: true, useProduction: true }
|
|
},
|
|
|
|
// Email system
|
|
emailConfig: {
|
|
ports: [25, 587, 465],
|
|
hostname: 'mail.example.com',
|
|
domains: [{ domain: 'example.com', dnsMode: 'external-dns' }],
|
|
routes: [
|
|
{
|
|
name: 'inbound-mail',
|
|
match: { recipients: '*@example.com' },
|
|
action: { type: 'process', process: { scan: true, dkim: true, queue: 'normal' } }
|
|
}
|
|
]
|
|
},
|
|
|
|
// Authoritative DNS
|
|
dnsNsDomains: ['ns1.example.com', 'ns2.example.com'],
|
|
dnsScopes: ['example.com'],
|
|
publicIp: '203.0.113.1',
|
|
dnsRecords: [
|
|
{ name: 'example.com', type: 'A', value: '203.0.113.1' },
|
|
{ name: 'www.example.com', type: 'CNAME', value: 'example.com' }
|
|
],
|
|
|
|
// RADIUS authentication
|
|
radiusConfig: {
|
|
authPort: 1812,
|
|
acctPort: 1813,
|
|
clients: [
|
|
{ name: 'switch-1', ipRange: '192.168.1.0/24', secret: 'radius-secret', enabled: true }
|
|
],
|
|
vlanAssignment: {
|
|
defaultVlan: 100,
|
|
allowUnknownMacs: true,
|
|
mappings: [
|
|
{ mac: 'aa:bb:cc:dd:ee:ff', vlan: 10, enabled: true },
|
|
{ mac: 'aa:bb:cc', vlan: 20, enabled: true } // OUI prefix
|
|
]
|
|
},
|
|
accounting: { enabled: true, retentionDays: 30 }
|
|
},
|
|
|
|
// Persistent storage
|
|
storage: { fsPath: '/var/lib/dcrouter/data' },
|
|
|
|
// Cache database
|
|
cacheConfig: { enabled: true, storagePath: '/etc/dcrouter/tsmdb' },
|
|
|
|
// TLS & ACME
|
|
tls: { contactEmail: 'admin@example.com' },
|
|
dnsChallenge: { cloudflareApiKey: process.env.CLOUDFLARE_API_KEY }
|
|
});
|
|
|
|
await router.start();
|
|
// OpsServer dashboard available at http://localhost:3000
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### System Overview
|
|
|
|
```mermaid
|
|
graph TB
|
|
subgraph "External Traffic"
|
|
HTTP[HTTP/HTTPS Clients]
|
|
SMTP[SMTP Clients]
|
|
TCP[TCP Clients]
|
|
DNS[DNS Queries]
|
|
RAD[RADIUS Clients]
|
|
end
|
|
|
|
subgraph "DcRouter Core"
|
|
DC[DcRouter Orchestrator]
|
|
SP[SmartProxy Engine]
|
|
ES[Unified Email Server]
|
|
DS[DNS Server]
|
|
RS[RADIUS Server]
|
|
CM[Certificate Manager]
|
|
OS[OpsServer Dashboard]
|
|
MM[Metrics Manager]
|
|
SM[Storage Manager]
|
|
CD[Cache Database]
|
|
end
|
|
|
|
subgraph "Backend Services"
|
|
WEB[Web Services]
|
|
MAIL[Mail Servers]
|
|
DB[Databases]
|
|
API[Internal APIs]
|
|
end
|
|
|
|
HTTP --> SP
|
|
TCP --> SP
|
|
SMTP --> ES
|
|
DNS --> DS
|
|
RAD --> RS
|
|
|
|
DC --> SP
|
|
DC --> ES
|
|
DC --> DS
|
|
DC --> RS
|
|
DC --> CM
|
|
DC --> OS
|
|
DC --> MM
|
|
DC --> SM
|
|
DC --> CD
|
|
|
|
SP --> WEB
|
|
SP --> API
|
|
ES --> MAIL
|
|
ES --> DB
|
|
|
|
CM -.-> SP
|
|
CM -.-> ES
|
|
```
|
|
|
|
### Core Components
|
|
|
|
| Component | Description |
|
|
|-----------|-------------|
|
|
| **DcRouter** | Central orchestrator — starts, stops, and coordinates all services |
|
|
| **SmartProxy** | High-performance HTTP/HTTPS and TCP/SNI proxy with route-based config |
|
|
| **UnifiedEmailServer** | Full SMTP server with pattern-based routing, DKIM, queue management |
|
|
| **DNS Server** | Authoritative DNS with dynamic records, DKIM TXT auto-generation |
|
|
| **RADIUS Server** | Network authentication with MAB, VLAN assignment, and accounting |
|
|
| **OpsServer** | Web dashboard + TypedRequest API for monitoring and management |
|
|
| **MetricsManager** | Real-time metrics collection (CPU, memory, email, DNS, security) |
|
|
| **StorageManager** | Pluggable key-value storage (filesystem, custom, or in-memory) |
|
|
| **CacheDb** | Embedded MongoDB-compatible database for persistent caching |
|
|
|
|
## Configuration Reference
|
|
|
|
### `IDcRouterOptions`
|
|
|
|
```typescript
|
|
interface IDcRouterOptions {
|
|
// ── Traffic Routing ────────────────────────────────────────────
|
|
/** SmartProxy config for HTTP/HTTPS and TCP/SNI routing */
|
|
smartProxyConfig?: ISmartProxyOptions;
|
|
|
|
// ── Email ──────────────────────────────────────────────────────
|
|
/** Unified email server configuration */
|
|
emailConfig?: {
|
|
ports: number[]; // e.g. [25, 587, 465]
|
|
hostname: string; // e.g. 'mail.example.com'
|
|
domains: IEmailDomainConfig[]; // Domain infrastructure
|
|
routes: IEmailRoute[]; // Routing rules
|
|
useSocketHandler?: boolean; // Direct socket passing (no port binding)
|
|
auth?: { required?: boolean; methods?: ('PLAIN'|'LOGIN'|'OAUTH2')[]; users?: Array<{username: string; password: string}> };
|
|
tls?: { certPath?: string; keyPath?: string; caPath?: string };
|
|
maxMessageSize?: number;
|
|
defaults?: {
|
|
dnsMode?: 'forward' | 'internal-dns' | 'external-dns';
|
|
dkim?: IEmailDomainConfig['dkim'];
|
|
rateLimits?: IEmailDomainConfig['rateLimits'];
|
|
};
|
|
};
|
|
|
|
/** Custom email port mapping overrides */
|
|
emailPortConfig?: {
|
|
portMapping?: Record<number, number>;
|
|
portSettings?: Record<number, any>;
|
|
receivedEmailsPath?: string;
|
|
};
|
|
|
|
// ── DNS ────────────────────────────────────────────────────────
|
|
/** Nameserver domains — get A records automatically */
|
|
dnsNsDomains?: string[]; // e.g. ['ns1.example.com', 'ns2.example.com']
|
|
/** Domains this server is authoritative for */
|
|
dnsScopes?: string[]; // e.g. ['example.com']
|
|
/** Public IP for NS A records */
|
|
publicIp?: string;
|
|
/** Ingress proxy IPs (hides real server IP) */
|
|
proxyIps?: string[];
|
|
/** Custom DNS records */
|
|
dnsRecords?: Array<{
|
|
name: string;
|
|
type: 'A' | 'AAAA' | 'CNAME' | 'MX' | 'TXT' | 'NS' | 'SOA';
|
|
value: string;
|
|
ttl?: number;
|
|
useIngressProxy?: boolean;
|
|
}>;
|
|
|
|
// ── RADIUS ─────────────────────────────────────────────────────
|
|
/** RADIUS server for network authentication */
|
|
radiusConfig?: {
|
|
authPort?: number; // default: 1812
|
|
acctPort?: number; // default: 1813
|
|
clients: IRadiusClient[];
|
|
vlanAssignment?: IVlanManagerConfig;
|
|
accounting?: { enabled: boolean; retentionDays?: number };
|
|
};
|
|
|
|
// ── TLS & Certificates ────────────────────────────────────────
|
|
tls?: {
|
|
contactEmail: string;
|
|
domain?: string;
|
|
certPath?: string;
|
|
keyPath?: string;
|
|
};
|
|
dnsChallenge?: { cloudflareApiKey?: string };
|
|
|
|
// ── Storage & Caching ─────────────────────────────────────────
|
|
storage?: {
|
|
fsPath?: string;
|
|
readFunction?: (key: string) => Promise<string>;
|
|
writeFunction?: (key: string, value: string) => Promise<void>;
|
|
};
|
|
cacheConfig?: {
|
|
enabled?: boolean; // default: true
|
|
storagePath?: string; // default: '/etc/dcrouter/tsmdb'
|
|
dbName?: string; // default: 'dcrouter'
|
|
cleanupIntervalHours?: number; // default: 1
|
|
ttlConfig?: {
|
|
emails?: number; // default: 30 days
|
|
ipReputation?: number; // default: 1 day
|
|
bounces?: number; // default: 30 days
|
|
dkimKeys?: number; // default: 90 days
|
|
suppression?: number; // default: 30 days
|
|
};
|
|
};
|
|
}
|
|
```
|
|
|
|
## HTTP/HTTPS & TCP/SNI Routing
|
|
|
|
DcRouter uses [SmartProxy](https://code.foss.global/push.rocks/smartproxy) for all HTTP/HTTPS and TCP/SNI routing. Routes are pattern-matched by domain, port, or both.
|
|
|
|
### HTTPS with Auto-TLS
|
|
|
|
```typescript
|
|
{
|
|
name: 'api-gateway',
|
|
match: { domains: ['api.example.com'], ports: [443] },
|
|
action: {
|
|
type: 'forward',
|
|
targets: [{ host: '192.168.1.20', port: 8080 }],
|
|
tls: { mode: 'terminate', certificate: 'auto' }
|
|
}
|
|
}
|
|
```
|
|
|
|
### TLS Passthrough (SNI Routing)
|
|
|
|
```typescript
|
|
{
|
|
name: 'secure-backend',
|
|
match: { domains: ['secure.example.com'], ports: [8443] },
|
|
action: {
|
|
type: 'forward',
|
|
targets: [{ host: '192.168.1.40', port: 8443 }],
|
|
tls: { mode: 'passthrough' }
|
|
}
|
|
}
|
|
```
|
|
|
|
### TCP Port Range Forwarding
|
|
|
|
```typescript
|
|
{
|
|
name: 'database-cluster',
|
|
match: { ports: [{ from: 5432, to: 5439 }] },
|
|
action: {
|
|
type: 'forward',
|
|
targets: [{ host: '192.168.1.30', port: 'preserve' }],
|
|
security: { ipAllowList: ['192.168.1.0/24'] }
|
|
}
|
|
}
|
|
```
|
|
|
|
### HTTP Redirect
|
|
|
|
```typescript
|
|
{
|
|
name: 'http-to-https',
|
|
match: { ports: [80] },
|
|
action: { type: 'redirect', redirect: { to: 'https://{domain}{path}' } }
|
|
}
|
|
```
|
|
|
|
## Email System
|
|
|
|
The email system is built around the **UnifiedEmailServer**, which handles SMTP sessions, route matching, delivery queuing, DKIM signing, and all email processing in a single unified component.
|
|
|
|
### Email Domain Configuration
|
|
|
|
Domains define _infrastructure_ — how DNS and DKIM are handled for each domain:
|
|
|
|
#### Forward Mode
|
|
Simple forwarding without local DNS management:
|
|
```typescript
|
|
{
|
|
domain: 'forwarded.com',
|
|
dnsMode: 'forward',
|
|
dns: { forward: { skipDnsValidation: true, targetDomain: 'mail.target.com' } }
|
|
}
|
|
```
|
|
|
|
#### Internal DNS Mode
|
|
Uses DcRouter's built-in DNS server (requires `dnsNsDomains` + `dnsScopes`):
|
|
```typescript
|
|
{
|
|
domain: 'mail.example.com',
|
|
dnsMode: 'internal-dns',
|
|
dns: { internal: { mxPriority: 10, ttl: 3600 } },
|
|
dkim: { selector: 'mail2024', keySize: 2048, rotateKeys: true, rotationInterval: 90 }
|
|
}
|
|
```
|
|
|
|
#### External DNS Mode
|
|
Uses existing DNS infrastructure with validation:
|
|
```typescript
|
|
{
|
|
domain: 'mail.external.com',
|
|
dnsMode: 'external-dns',
|
|
dns: { external: { requiredRecords: ['MX', 'SPF', 'DKIM', 'DMARC'] } },
|
|
rateLimits: {
|
|
inbound: { messagesPerMinute: 100, connectionsPerIp: 10 },
|
|
outbound: { messagesPerMinute: 200 }
|
|
}
|
|
}
|
|
```
|
|
|
|
### Email Route Actions
|
|
|
|
Routes define _behavior_ — what happens when an email matches:
|
|
|
|
#### Forward 📤
|
|
Routes emails to an external SMTP server:
|
|
```typescript
|
|
{
|
|
name: 'forward-to-internal',
|
|
match: { recipients: '*@company.com' },
|
|
action: {
|
|
type: 'forward',
|
|
forward: {
|
|
host: 'internal-mail.company.com',
|
|
port: 25,
|
|
auth: { user: 'relay-user', pass: 'relay-pass' },
|
|
addHeaders: { 'X-Forwarded-By': 'dcrouter' }
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Process ⚙️
|
|
Full MTA processing with content scanning and delivery queues:
|
|
```typescript
|
|
{
|
|
name: 'process-notifications',
|
|
match: { recipients: '*@notifications.company.com' },
|
|
action: {
|
|
type: 'process',
|
|
process: { scan: true, dkim: true, queue: 'priority' }
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Deliver 📥
|
|
Local mailbox delivery:
|
|
```typescript
|
|
{
|
|
name: 'deliver-local',
|
|
match: { recipients: '*@local.company.com' },
|
|
action: { type: 'deliver' }
|
|
}
|
|
```
|
|
|
|
#### Reject 🚫
|
|
Reject with custom SMTP response code:
|
|
```typescript
|
|
{
|
|
name: 'reject-spam-domain',
|
|
match: { senders: '*@spam-domain.com', sizeRange: { min: 1000000 } },
|
|
action: {
|
|
type: 'reject',
|
|
reject: { code: 550, message: 'Message rejected due to policy' }
|
|
}
|
|
}
|
|
```
|
|
|
|
### Route Matching
|
|
|
|
Routes support powerful matching criteria:
|
|
|
|
```typescript
|
|
// Recipient patterns
|
|
match: { recipients: '*@example.com' } // All addresses at domain
|
|
match: { recipients: 'admin@*' } // "admin" at any domain
|
|
match: { senders: ['*@trusted.com', '*@vip.com'] } // Multiple sender patterns
|
|
|
|
// IP-based matching (CIDR)
|
|
match: { clientIp: '192.168.0.0/16' }
|
|
match: { clientIp: ['10.0.0.0/8', '172.16.0.0/12'] }
|
|
|
|
// Authentication state
|
|
match: { authenticated: true }
|
|
|
|
// Header matching
|
|
match: { headers: { 'X-Priority': 'high', 'Subject': /urgent|emergency/i } }
|
|
|
|
// Size and content
|
|
match: { sizeRange: { min: 1000, max: 5000000 }, hasAttachments: true }
|
|
match: { subject: /invoice|receipt/i }
|
|
```
|
|
|
|
### Socket-Handler Mode 🔌
|
|
|
|
When `useSocketHandler: true` is set, SmartProxy passes sockets directly to the email server — no internal port binding, lower latency, and fewer open ports:
|
|
|
|
```
|
|
Traditional: External Port → SmartProxy → Internal Port → Email Server
|
|
Socket Mode: External Port → SmartProxy → (direct socket) → Email Server
|
|
```
|
|
|
|
### Email Security Stack
|
|
|
|
- **DKIM** — Automatic key generation, signing, and rotation for all domains
|
|
- **SPF** — Sender Policy Framework verification on inbound mail
|
|
- **DMARC** — Domain-based Message Authentication verification
|
|
- **IP Reputation** — Real-time IP reputation checking with caching
|
|
- **Content Scanning** — Spam, virus, and attachment scanning
|
|
- **Rate Limiting** — Hierarchical limits (global → domain → sender)
|
|
- **Bounce Management** — Automatic bounce detection and suppression lists
|
|
|
|
### Email Deliverability
|
|
|
|
- **IP Warmup Manager** — Multi-stage warmup schedules for new IPs
|
|
- **Sender Reputation Monitor** — Per-domain reputation tracking and scoring
|
|
- **Connection Pooling** — Pooled outbound SMTP connections per destination
|
|
|
|
## DNS Server
|
|
|
|
DcRouter includes an authoritative DNS server built on [smartdns](https://code.foss.global/push.rocks/smartdns). It handles standard UDP DNS on port 53 and DNS-over-HTTPS via SmartProxy socket handler.
|
|
|
|
### Enabling DNS
|
|
|
|
DNS is activated when both `dnsNsDomains` and `dnsScopes` are configured:
|
|
|
|
```typescript
|
|
const router = new DcRouter({
|
|
dnsNsDomains: ['ns1.example.com', 'ns2.example.com'],
|
|
dnsScopes: ['example.com'],
|
|
publicIp: '203.0.113.1',
|
|
dnsRecords: [
|
|
{ name: 'example.com', type: 'A', value: '203.0.113.1' },
|
|
{ name: 'www.example.com', type: 'CNAME', value: 'example.com' },
|
|
{ name: 'example.com', type: 'MX', value: '10:mail.example.com' },
|
|
{ name: 'example.com', type: 'TXT', value: 'v=spf1 a mx ~all' }
|
|
]
|
|
});
|
|
```
|
|
|
|
### Automatic DNS Records
|
|
|
|
DcRouter auto-generates:
|
|
- **NS records** for all domains in `dnsScopes`
|
|
- **SOA records** for authoritative zones
|
|
- **A records** for nameserver domains (`dnsNsDomains`)
|
|
- **MX, SPF, DKIM, DMARC records** for email domains with `internal-dns` mode
|
|
- **ACME challenge records** for certificate provisioning
|
|
|
|
### Ingress Proxy Support
|
|
|
|
When `proxyIps` is configured, A records with `useIngressProxy: true` (default) will use the proxy IP instead of the real server IP — hiding your origin:
|
|
|
|
```typescript
|
|
{
|
|
proxyIps: ['198.51.100.1', '198.51.100.2'],
|
|
dnsRecords: [
|
|
{ name: 'example.com', type: 'A', value: '203.0.113.1' }, // Will resolve to 198.51.100.1
|
|
{ name: 'ns1.example.com', type: 'A', value: '203.0.113.1', useIngressProxy: false } // Stays real IP
|
|
]
|
|
}
|
|
```
|
|
|
|
## RADIUS Server
|
|
|
|
DcRouter includes a RADIUS server for network access control, built on [smartradius](https://code.foss.global/push.rocks/smartradius).
|
|
|
|
### Configuration
|
|
|
|
```typescript
|
|
const router = new DcRouter({
|
|
radiusConfig: {
|
|
authPort: 1812,
|
|
acctPort: 1813,
|
|
clients: [
|
|
{
|
|
name: 'core-switch',
|
|
ipRange: '192.168.1.0/24',
|
|
secret: 'shared-secret',
|
|
enabled: true
|
|
}
|
|
],
|
|
vlanAssignment: {
|
|
defaultVlan: 100,
|
|
allowUnknownMacs: true,
|
|
mappings: [
|
|
{ mac: 'aa:bb:cc:dd:ee:ff', vlan: 10, enabled: true }, // Exact MAC
|
|
{ mac: 'aa:bb:cc', vlan: 20, enabled: true }, // OUI prefix
|
|
]
|
|
},
|
|
accounting: {
|
|
enabled: true,
|
|
retentionDays: 30
|
|
}
|
|
}
|
|
});
|
|
```
|
|
|
|
### Components
|
|
|
|
| Component | Purpose |
|
|
|-----------|---------|
|
|
| **RadiusServer** | Main RADIUS server handling auth + accounting requests |
|
|
| **VlanManager** | MAC-to-VLAN mapping with exact, OUI, and wildcard patterns |
|
|
| **AccountingManager** | Session tracking, traffic metering, start/stop/interim updates |
|
|
|
|
### OpsServer API
|
|
|
|
RADIUS is fully manageable at runtime via the OpsServer API:
|
|
- Client management (add/remove/list NAS devices)
|
|
- VLAN mapping CRUD operations
|
|
- Session monitoring and forced disconnects
|
|
- Accounting summaries and statistics
|
|
|
|
## Storage & Caching
|
|
|
|
### StorageManager
|
|
|
|
Provides a unified key-value interface with three backends:
|
|
|
|
```typescript
|
|
// Filesystem backend
|
|
storage: { fsPath: '/var/lib/dcrouter/data' }
|
|
|
|
// Custom backend (Redis, S3, etc.)
|
|
storage: {
|
|
readFunction: async (key) => await redis.get(key),
|
|
writeFunction: async (key, value) => await redis.set(key, value)
|
|
}
|
|
|
|
// In-memory (development only — data lost on restart)
|
|
// Simply omit the storage config
|
|
```
|
|
|
|
Used for: DKIM keys, email routes, bounce/suppression lists, IP reputation data, domain configs.
|
|
|
|
### Cache Database
|
|
|
|
An embedded MongoDB-compatible database (via smartdata + TsmDb) for persistent caching with automatic TTL cleanup:
|
|
|
|
```typescript
|
|
cacheConfig: {
|
|
enabled: true,
|
|
storagePath: '/etc/dcrouter/tsmdb',
|
|
dbName: 'dcrouter',
|
|
cleanupIntervalHours: 1,
|
|
ttlConfig: {
|
|
emails: 30, // days
|
|
ipReputation: 1, // days
|
|
bounces: 30, // days
|
|
dkimKeys: 90, // days
|
|
suppression: 30 // days
|
|
}
|
|
}
|
|
```
|
|
|
|
Cached document types: `CachedEmail`, `CachedIPReputation`, `CachedBounce`, `CachedSuppression`, `CachedDKIMKey`.
|
|
|
|
## Security Features
|
|
|
|
### IP Reputation Checking
|
|
|
|
Automatic IP reputation checks on inbound connections with configurable caching:
|
|
|
|
```typescript
|
|
// IP reputation is checked automatically for inbound SMTP connections.
|
|
// Results are cached according to cacheConfig.ttlConfig.ipReputation.
|
|
```
|
|
|
|
### Rate Limiting
|
|
|
|
Hierarchical rate limits with three levels of specificity:
|
|
|
|
```typescript
|
|
// Global defaults (via emailConfig.defaults.rateLimits)
|
|
defaults: {
|
|
rateLimits: {
|
|
inbound: { messagesPerMinute: 50, connectionsPerIp: 5, recipientsPerMessage: 50 },
|
|
outbound: { messagesPerMinute: 100 }
|
|
}
|
|
}
|
|
|
|
// Per-domain overrides (in domain config)
|
|
{
|
|
domain: 'high-volume.com',
|
|
rateLimits: {
|
|
outbound: { messagesPerMinute: 500 } // Override for this domain
|
|
}
|
|
}
|
|
```
|
|
|
|
**Precedence**: Domain-specific > Pattern-specific > Global
|
|
|
|
### Content Scanning
|
|
|
|
```typescript
|
|
action: {
|
|
type: 'process',
|
|
options: {
|
|
contentScanning: true,
|
|
scanners: [
|
|
{ type: 'spam', threshold: 5.0, action: 'tag' },
|
|
{ type: 'virus', action: 'reject' },
|
|
{ type: 'attachment', blockedExtensions: ['.exe', '.bat', '.scr'], action: 'reject' }
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
## OpsServer Dashboard
|
|
|
|
The OpsServer provides a web-based management interface served on port 3000. It's built with modern web components using [@design.estate/dees-catalog](https://code.foss.global/design.estate/dees-catalog).
|
|
|
|
### Dashboard Views
|
|
|
|
| View | Description |
|
|
|------|-------------|
|
|
| 📊 **Overview** | Real-time server stats, CPU/memory, connection counts, email throughput |
|
|
| 🌐 **Network** | Active connections, top IPs, throughput rates, SmartProxy metrics |
|
|
| 📧 **Email** | Queue monitoring (queued/sent/failed), bounce records, security incidents |
|
|
| 📜 **Logs** | Real-time log viewer with level filtering and search |
|
|
| ⚙️ **Configuration** | Read-only view of current system configuration |
|
|
| 🛡️ **Security** | IP reputation, rate limit status, blocked connections |
|
|
|
|
### API Endpoints
|
|
|
|
All management is done via TypedRequest over HTTP POST to `/typedrequest`:
|
|
|
|
```typescript
|
|
// Authentication
|
|
{ method: 'adminLogin', data: { username, password } }
|
|
{ method: 'verifyIdentity', data: { identity } }
|
|
|
|
// Statistics
|
|
{ method: 'getServerStatistics', data: { identity } }
|
|
{ method: 'getCombinedMetrics', data: { identity } }
|
|
{ method: 'getHealthStatus', data: { identity } }
|
|
|
|
// Email Operations
|
|
{ method: 'getQueuedEmails', data: { identity } }
|
|
{ method: 'getSentEmails', data: { identity } }
|
|
{ method: 'getFailedEmails', data: { identity } }
|
|
{ method: 'resendEmail', data: { identity, emailId } }
|
|
{ method: 'getBounceRecords', data: { identity } }
|
|
|
|
// Configuration (read-only)
|
|
{ method: 'getConfiguration', data: { identity } }
|
|
|
|
// Logs
|
|
{ method: 'getLogs', data: { identity, level, limit } }
|
|
|
|
// RADIUS
|
|
{ method: 'getRadiusSessions', data: { identity } }
|
|
{ method: 'getRadiusClients', data: { identity } }
|
|
{ method: 'getRadiusStatistics', data: { identity } }
|
|
```
|
|
|
|
## API Reference
|
|
|
|
### DcRouter Class
|
|
|
|
```typescript
|
|
import { DcRouter } from '@serve.zone/dcrouter';
|
|
|
|
const router = new DcRouter(options: IDcRouterOptions);
|
|
```
|
|
|
|
#### Methods
|
|
|
|
| Method | Description |
|
|
|--------|-------------|
|
|
| `start(): Promise<void>` | Start all configured services |
|
|
| `stop(): Promise<void>` | Gracefully stop all services |
|
|
| `updateSmartProxyConfig(config): Promise<void>` | Hot-update SmartProxy routes |
|
|
| `updateEmailConfig(config): Promise<void>` | Hot-update email configuration |
|
|
| `updateEmailRoutes(routes): Promise<void>` | Update email routing rules at runtime |
|
|
| `updateRadiusConfig(config): Promise<void>` | Hot-update RADIUS configuration |
|
|
| `getStats(): any` | Get real-time statistics from all services |
|
|
|
|
#### Properties
|
|
|
|
| Property | Type | Description |
|
|
|----------|------|-------------|
|
|
| `options` | `IDcRouterOptions` | Current configuration |
|
|
| `smartProxy` | `SmartProxy` | SmartProxy instance |
|
|
| `emailServer` | `UnifiedEmailServer` | Email server instance |
|
|
| `dnsServer` | `DnsServer` | DNS server instance |
|
|
| `radiusServer` | `RadiusServer` | RADIUS server instance |
|
|
| `storageManager` | `StorageManager` | Storage backend |
|
|
| `opsServer` | `OpsServer` | OpsServer/dashboard instance |
|
|
| `metricsManager` | `MetricsManager` | Metrics collector |
|
|
| `cacheDb` | `CacheDb` | Cache database instance |
|
|
|
|
## Sub-Modules
|
|
|
|
DcRouter is published as a monorepo with separately-installable interface and web packages:
|
|
|
|
| Package | Description | Install |
|
|
|---------|-------------|---------|
|
|
| [`@serve.zone/dcrouter`](https://www.npmjs.com/package/@serve.zone/dcrouter) | Main package — the full router | `pnpm add @serve.zone/dcrouter` |
|
|
| [`@serve.zone/dcrouter-interfaces`](https://www.npmjs.com/package/@serve.zone/dcrouter-interfaces) | TypedRequest interfaces for the OpsServer API | `pnpm add @serve.zone/dcrouter-interfaces` |
|
|
| [`@serve.zone/dcrouter-web`](https://www.npmjs.com/package/@serve.zone/dcrouter-web) | Web dashboard components | `pnpm add @serve.zone/dcrouter-web` |
|
|
|
|
You can also import interfaces directly from the main package:
|
|
|
|
```typescript
|
|
import { data, requests } from '@serve.zone/dcrouter/interfaces';
|
|
```
|
|
|
|
## Testing
|
|
|
|
DcRouter includes a comprehensive test suite with **198 test files** covering all system components:
|
|
|
|
- **SMTP Protocol** — EHLO, MAIL FROM, RCPT TO, DATA, STARTTLS, AUTH, pipelining
|
|
- **Email Routing** — Pattern matching, route priorities, all action types
|
|
- **Email Security** — DKIM, SPF, DMARC, content scanning, rate limiting
|
|
- **DNS** — Record management, socket handler, validation, mode switching
|
|
- **RADIUS** — Authentication, VLAN assignment, accounting
|
|
- **Deliverability** — IP warmup, reputation monitoring, bounce management
|
|
- **Storage & Cache** — All backends, TTL cleanup, persistence
|
|
- **OpsServer** — API authentication, protected endpoints, statistics
|
|
- **Integration** — Full end-to-end workflows
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# Run all tests
|
|
pnpm test
|
|
|
|
# Run a specific test file
|
|
tstest test/test.email.router.ts --verbose
|
|
|
|
# Run SMTP protocol suite
|
|
tstest test/suite/smtpserver_commands/test.cmd-01.ehlo-command.ts --verbose
|
|
```
|
|
|
|
## License and Legal Information
|
|
|
|
This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
|
|
|
|
**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
|
|
|
|
### Trademarks
|
|
|
|
This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
|
|
|
|
Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
|
|
|
|
### Company Information
|
|
|
|
Task Venture Capital GmbH
|
|
Registered at District Court Bremen HRB 35230 HB, Germany
|
|
|
|
For any legal inquiries or further information, please contact us via email at hello@task.vc.
|
|
|
|
By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.
|