push.rocks/smartproxy
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(nftables): Add NFTables integration for kernel-level forwarding and update documentation, tests, and helper functions

Browse Source
This commit is contained in:
Philipp Kunz
2025-05-15 19:39:09 +00:00
parent 4568623600
commit 5d0b68da61
19 changed files with 977 additions and 1068 deletions
Download Patch File Download Diff File Expand all files Collapse all files

234
readme.md
View File

@ -9,6 +9,7 @@ A unified high-performance proxy toolkit for Node.js, with **SmartProxy** as the
- **Multiple Action Types**: Forward (with TLS modes), redirect, or block traffic
- **Dynamic Port Management**: Add or remove listening ports at runtime without restart
- **Security Features**: IP allowlists, connection limits, timeouts, and more
- **NFTables Integration**: High-performance kernel-level packet forwarding with Linux NFTables
## Project Architecture Overview
@ -71,6 +72,8 @@ SmartProxy has been restructured using a modern, modular architecture with a uni
Helper functions for common redirect and security configurations
- **createLoadBalancerRoute**, **createHttpsServer**
Helper functions for complex configurations
- **createNfTablesRoute**, **createNfTablesTerminateRoute**
Helper functions for NFTables-based high-performance kernel-level routing
### Specialized Components
@ -108,7 +111,7 @@ npm install @push.rocks/smartproxy
## Quick Start with SmartProxy
SmartProxy v16.0.0 continues the evolution of the unified route-based configuration system making your proxy setup more flexible and intuitive with improved helper functions.
SmartProxy v18.0.0 continues the evolution of the unified route-based configuration system making your proxy setup more flexible and intuitive with improved helper functions and NFTables integration for high-performance kernel-level routing.
```typescript
import {
@ -122,7 +125,9 @@ import {
createStaticFileRoute,
createApiRoute,
createWebSocketRoute,
createSecurityConfig
createSecurityConfig,
createNfTablesRoute,
createNfTablesTerminateRoute
} from '@push.rocks/smartproxy';
// Create a new SmartProxy instance with route-based configuration
@ -185,7 +190,22 @@ const proxy = new SmartProxy({
maxConnections: 1000
})
}
)
),
// High-performance NFTables route (requires root/sudo)
createNfTablesRoute('fast.example.com', { host: 'backend-server', port: 8080 }, {
ports: 80,
protocol: 'tcp',
preserveSourceIP: true,
ipAllowList: ['10.0.0.*']
}),
// NFTables HTTPS termination for ultra-fast TLS handling
createNfTablesTerminateRoute('secure-fast.example.com', { host: 'backend-ssl', port: 443 }, {
ports: 443,
certificate: 'auto',
maxRate: '100mbps'
})
],
// Global settings that apply to all routes
@ -319,6 +339,12 @@ interface IRouteAction {
// Advanced options
advanced?: IRouteAdvanced;
// Forwarding engine selection
forwardingEngine?: 'node' | 'nftables';
// NFTables-specific options
nftables?: INfTablesOptions;
}
```
@ -349,6 +375,25 @@ interface IRouteTls {
- **terminate:** Terminate TLS and forward as HTTP
- **terminate-and-reencrypt:** Terminate TLS and create a new TLS connection to the backend
**Forwarding Engine:**
When `forwardingEngine` is specified, it determines how packets are forwarded:
- **node:** (default) Application-level forwarding using Node.js
- **nftables:** Kernel-level forwarding using Linux NFTables (requires root privileges)
**NFTables Options:**
When using `forwardingEngine: 'nftables'`, you can configure:
```typescript
interface INfTablesOptions {
protocol?: 'tcp' | 'udp' | 'all';
preserveSourceIP?: boolean;
maxRate?: string; // Rate limiting (e.g., '100mbps')
priority?: number; // QoS priority
tableName?: string; // Custom NFTables table name
useIPSets?: boolean; // Use IP sets for performance
useAdvancedNAT?: boolean; // Use connection tracking
}
```
**Redirect Action:**
When `type: 'redirect'`, the client is redirected:
```typescript
@ -459,6 +504,35 @@ Routes with higher priority values are matched first, allowing you to create spe
priority: 100,
tags: ['api', 'secure', 'internal']
}
// Example with NFTables forwarding engine
{
match: {
ports: [80, 443],
domains: 'high-traffic.example.com'
},
action: {
type: 'forward',
target: {
host: 'backend-server',
port: 8080
},
forwardingEngine: 'nftables', // Use kernel-level forwarding
nftables: {
protocol: 'tcp',
preserveSourceIP: true,
maxRate: '1gbps',
useIPSets: true
},
security: {
ipAllowList: ['10.0.0.*'],
blockedIps: ['malicious.ip.range.*']
}
},
name: 'High Performance NFTables Route',
description: 'Kernel-level forwarding for maximum performance',
priority: 150
}
```
### Using Helper Functions
@ -489,6 +563,8 @@ Available helper functions:
- `createStaticFileRoute()` - Create a route for serving static files
- `createApiRoute()` - Create an API route with path matching and CORS support
- `createWebSocketRoute()` - Create a route for WebSocket connections
- `createNfTablesRoute()` - Create a high-performance NFTables route
- `createNfTablesTerminateRoute()` - Create an NFTables route with TLS termination
- `createPortRange()` - Helper to create port range configurations
- `createSecurityConfig()` - Helper to create security configuration objects
- `createBlockRoute()` - Create a route to block specific traffic
@ -589,6 +665,16 @@ Available helper functions:
await proxy.removeListeningPort(8081);
```
9. **High-Performance NFTables Routing**
```typescript
// Use kernel-level packet forwarding for maximum performance
createNfTablesRoute('high-traffic.example.com', { host: 'backend', port: 8080 }, {
ports: 80,
preserveSourceIP: true,
maxRate: '1gbps'
})
```
## Other Components
While SmartProxy provides a unified API for most needs, you can also use individual components:
@ -694,16 +780,137 @@ const redirect = new SslRedirect(80);
await redirect.start();
```
## Migration to v16.0.0
## NFTables Integration
Version 16.0.0 completes the migration to a fully unified route-based configuration system with improved helper functions:
SmartProxy v18.0.0 includes full integration with Linux NFTables for high-performance kernel-level packet forwarding. NFTables operates directly in the Linux kernel, providing much better performance than user-space proxying for high-traffic scenarios.
### When to Use NFTables
NFTables routing is ideal for:
- High-traffic TCP/UDP forwarding where performance is critical
- Port forwarding scenarios where you need minimal latency
- Load balancing across multiple backend servers
- Security filtering with IP allowlists/blocklists at kernel level
### Requirements
NFTables support requires:
- Linux operating system with NFTables installed
- Root or sudo permissions to configure NFTables rules
- NFTables kernel modules loaded
### NFTables Route Configuration
Use the NFTables helper functions to create high-performance routes:
```typescript
import { SmartProxy, createNfTablesRoute, createNfTablesTerminateRoute } from '@push.rocks/smartproxy';
const proxy = new SmartProxy({
routes: [
// Basic TCP forwarding with NFTables
createNfTablesRoute('tcp-forward', {
host: 'backend-server',
port: 8080
}, {
ports: 80,
protocol: 'tcp'
}),
// NFTables with IP filtering
createNfTablesRoute('secure-tcp', {
host: 'secure-backend',
port: 8443
}, {
ports: 443,
ipAllowList: ['10.0.0.*', '192.168.1.*'],
preserveSourceIP: true
}),
// NFTables with QoS (rate limiting)
createNfTablesRoute('limited-service', {
host: 'api-server',
port: 3000
}, {
ports: 8080,
maxRate: '50mbps',
priority: 1
}),
// NFTables TLS termination
createNfTablesTerminateRoute('https-nftables', {
host: 'backend',
port: 8080
}, {
ports: 443,
certificate: 'auto',
useAdvancedNAT: true
})
]
});
await proxy.start();
```
### NFTables Route Options
The NFTables integration supports these options:
- `protocol`: 'tcp' | 'udp' | 'all' - Protocol to forward
- `preserveSourceIP`: boolean - Preserve client IP for backend
- `ipAllowList`: string[] - Allow only these IPs (glob patterns)
- `ipBlockList`: string[] - Block these IPs (glob patterns)
- `maxRate`: string - Rate limit (e.g., '100mbps', '1gbps')
- `priority`: number - QoS priority level
- `tableName`: string - Custom NFTables table name
- `useIPSets`: boolean - Use IP sets for better performance
- `useAdvancedNAT`: boolean - Enable connection tracking
### NFTables Status Monitoring
You can monitor the status of NFTables rules:
```typescript
// Get status of all NFTables rules
const nftStatus = await proxy.getNfTablesStatus();
// Status includes:
// - active: boolean
// - ruleCount: { total, added, removed }
// - packetStats: { forwarded, dropped }
// - lastUpdate: Date
```
### Performance Considerations
NFTables provides significantly better performance than application-level proxying:
- Operates at kernel level with minimal overhead
- Can handle millions of packets per second
- Direct packet forwarding without copying to userspace
- Hardware offload support on compatible network cards
### Limitations
NFTables routing has some limitations:
- Cannot modify HTTP headers or content
- Limited to basic NAT and forwarding operations
- Requires root permissions
- Linux-only (not available on Windows/macOS)
- No WebSocket message inspection
For scenarios requiring application-level features (header manipulation, WebSocket handling, etc.), use the standard SmartProxy routes without NFTables.
## Migration to v18.0.0
Version 18.0.0 continues the evolution with NFTables integration while maintaining the unified route-based configuration system:
### Key Changes
1. **Pure Route-Based API**: The configuration now exclusively uses the match/action pattern with no legacy interfaces
2. **Improved Helper Functions**: Enhanced helper functions with cleaner parameter signatures
3. **Removed Legacy Support**: Legacy domain-based APIs have been completely removed
4. **More Route Pattern Helpers**: Additional helper functions for common routing patterns
1. **NFTables Integration**: High-performance kernel-level packet forwarding for Linux systems
2. **Pure Route-Based API**: The configuration now exclusively uses the match/action pattern with no legacy interfaces
3. **Improved Helper Functions**: Enhanced helper functions with cleaner parameter signatures
4. **Removed Legacy Support**: Legacy domain-based APIs have been completely removed
5. **More Route Pattern Helpers**: Additional helper functions for common routing patterns including NFTables routes
### Migration Example
@ -723,7 +930,7 @@ const proxy = new SmartProxy({
});
```
**Current Configuration (v16.0.0)**:
**Current Configuration (v18.0.0)**:
```typescript
import { SmartProxy, createHttpsTerminateRoute } from '@push.rocks/smartproxy';
@ -1212,6 +1419,13 @@ NetworkProxy now supports full route-based configuration including:
- Use higher priority for block routes to ensure they take precedence
- Enable `enableDetailedLogging` or `enableTlsDebugLogging` for debugging
### NFTables Integration
- Ensure NFTables is installed: `apt install nftables` or `yum install nftables`
- Verify root/sudo permissions for NFTables operations
- Check NFTables service is running: `systemctl status nftables`
- For debugging, check the NFTables rules: `nft list ruleset`
- Monitor NFTables rule status: `await proxy.getNfTablesStatus()`
### TLS/Certificates
- For certificate issues, check the ACME settings and domain validation
- Ensure domains are publicly accessible for Let's Encrypt validation