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

feat(docs): docs: replace IPTablesProxy references with NfTablesProxy in README and examples, updating configuration options and diagrams for advanced nftables features

Browse Source
This commit is contained in:
Philipp Kunz 2025-03-18 22:04:37 +00:00
parent 6b2765a429
commit 88a1891bcf
3 changed files with 85 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
changelog.md
View File

@ -1,5 +1,12 @@
# Changelog
## 2025-03-18 - 5.1.0 - feat(docs)
docs: replace IPTablesProxy references with NfTablesProxy in README and examples, updating configuration options and diagrams for advanced nftables features
- Updated README diagrams to reflect nftables integration for low-level port forwarding.
- Replaced all occurrences of 'IPTablesProxy' with 'NfTablesProxy' in documentation and code examples.
- Included additional details on QoS, advanced NAT, and IP set options in the configuration options section.
## 2025-03-18 - 5.0.0 - BREAKING CHANGE(nftables)
Replace IPTablesProxy with NfTablesProxy and update module exports in index.ts

104
readme.md
View File

@ -16,7 +16,7 @@ flowchart TB
HTTP80[HTTP Port 80\nSslRedirect]
HTTPS443[HTTPS Port 443\nNetworkProxy]
PortProxy[TCP Port Proxy\nwith SNI routing]
IPTables[IPTablesProxy]
NfTables[NfTablesProxy]
Router[ProxyRouter]
ACME[Port80Handler\nACME/Let's Encrypt]
Certs[(SSL Certificates)]
@ -40,7 +40,7 @@ flowchart TB
PortProxy -->|Direct TCP| Service2
PortProxy -->|Direct TCP| Service3
IPTables -.->|Low-level forwarding| PortProxy
NfTables -.->|Low-level forwarding| PortProxy
HTTP80 -.->|Challenge Response| ACME
ACME -.->|Generate/Manage| Certs
@ -197,7 +197,7 @@ sequenceDiagram
- **HTTP to HTTPS Redirection** - Automatically redirect HTTP requests to HTTPS
- **Let's Encrypt Integration** - Automatic certificate management using ACME protocol
- **IP Filtering** - Control access with IP allow/block lists using glob patterns
- **IPTables Integration** - Direct manipulation of iptables for low-level port forwarding
- **NfTables Integration** - Direct manipulation of nftables for advanced low-level port forwarding
- **Basic Authentication** - Support for basic auth on proxied routes
- **Connection Management** - Intelligent connection tracking and cleanup with configurable timeouts
- **Browser Compatibility** - Optimized for modern browsers with fixes for common TLS handshake issues
@ -315,13 +315,13 @@ const portProxy = new PortProxy({
portProxy.start();
```
### IPTables Port Forwarding
### NfTables Port Forwarding
```typescript
import { IPTablesProxy } from '@push.rocks/smartproxy';
import { NfTablesProxy } from '@push.rocks/smartproxy';
// Basic usage - forward single port
const basicProxy = new IPTablesProxy({
const basicProxy = new NfTablesProxy({
fromPort: 80,
toPort: 8080,
toHost: 'localhost',
@ -330,7 +330,7 @@ const basicProxy = new IPTablesProxy({
});
// Forward port ranges
const rangeProxy = new IPTablesProxy({
const rangeProxy = new NfTablesProxy({
fromPort: { from: 3000, to: 3010 }, // Forward ports 3000-3010
toPort: { from: 8000, to: 8010 }, // To ports 8000-8010
protocol: 'tcp', // TCP protocol (default)
@ -339,19 +339,26 @@ const rangeProxy = new IPTablesProxy({
});
// Multiple port specifications with IP filtering
const advancedProxy = new IPTablesProxy({
const advancedProxy = new NfTablesProxy({
fromPort: [80, 443, { from: 8000, to: 8010 }], // Multiple ports/ranges
toPort: [8080, 8443, { from: 18000, to: 18010 }],
allowedSourceIPs: ['10.0.0.0/8', '192.168.1.0/24'], // Only allow these IPs
bannedSourceIPs: ['192.168.1.100'], // Explicitly block these IPs
addJumpRule: true, // Use custom chain for better management
checkExistingRules: true // Check for duplicate rules
useIPSets: true, // Use IP sets for efficient IP management
forceCleanSlate: false // Clean all NfTablesProxy rules before starting
});
// NetworkProxy integration for SSL termination
const sslProxy = new IPTablesProxy({
// Advanced features: QoS, connection tracking, and NetworkProxy integration
const advancedProxy = new NfTablesProxy({
fromPort: 443,
toPort: 8443,
toHost: 'localhost',
useAdvancedNAT: true, // Use connection tracking for stateful NAT
qos: {
enabled: true,
maxRate: '10mbps', // Limit bandwidth
priority: 1 // Set traffic priority (1-10)
},
netProxyIntegration: {
enabled: true,
redirectLocalhost: true, // Redirect localhost traffic to NetworkProxy
@ -372,8 +379,25 @@ import { Port80Handler } from '@push.rocks/smartproxy';
const acmeHandler = new Port80Handler();
// Add domains to manage certificates for
acmeHandler.addDomain('example.com');
acmeHandler.addDomain('api.example.com');
acmeHandler.addDomain({
domainName: 'example.com',
sslRedirect: true,
acmeMaintenance: true
});
acmeHandler.addDomain({
domainName: 'api.example.com',
sslRedirect: true,
acmeMaintenance: true
});
// Support for glob pattern domains for routing (certificates not issued for glob patterns)
acmeHandler.addDomain({
domainName: '*.example.com',
sslRedirect: true,
acmeMaintenance: false, // Can't issue certificates for wildcard domains via HTTP-01
forward: { ip: '192.168.1.10', port: 8080 } // Forward requests to this target
});
```
## Configuration Options
@ -412,7 +436,7 @@ acmeHandler.addDomain('api.example.com');
| `enableDetailedLogging` | Enable detailed connection logging | false |
| `enableRandomizedTimeouts`| Randomize timeouts slightly to prevent thundering herd | true |
### IPTablesProxy Settings
### NfTablesProxy Settings
| Option | Description | Default |
|-----------------------|---------------------------------------------------|-------------|
@ -420,18 +444,32 @@ acmeHandler.addDomain('api.example.com');
| `toPort` | Destination port(s) or range(s) to forward to | - |
| `toHost` | Destination host to forward to | 'localhost' |
| `preserveSourceIP` | Preserve the original client IP | false |
| `deleteOnExit` | Remove iptables rules when process exits | false |
| `deleteOnExit` | Remove nftables rules when process exits | false |
| `protocol` | Protocol to forward ('tcp', 'udp', or 'all') | 'tcp' |
| `enableLogging` | Enable detailed logging | false |
| `ipv6Support` | Enable IPv6 support with ip6tables | false |
| `logFormat` | Format for logs ('plain' or 'json') | 'plain' |
| `ipv6Support` | Enable IPv6 support | false |
| `allowedSourceIPs` | Array of IP addresses/CIDR allowed to connect | - |
| `bannedSourceIPs` | Array of IP addresses/CIDR blocked from connecting | - |
| `forceCleanSlate` | Clear all IPTablesProxy rules before starting | false |
| `addJumpRule` | Add a custom chain for cleaner rule management | false |
| `checkExistingRules` | Check if rules already exist before adding | true |
| `useIPSets` | Use nftables sets for efficient IP management | true |
| `forceCleanSlate` | Clear all NfTablesProxy rules before starting | false |
| `tableName` | Custom table name | 'portproxy' |
| `maxRetries` | Maximum number of retries for failed commands | 3 |
| `retryDelayMs` | Delay between retries in milliseconds | 1000 |
| `useAdvancedNAT` | Use connection tracking for stateful NAT | false |
| `qos` | Quality of Service options (object) | - |
| `netProxyIntegration` | NetworkProxy integration options (object) | - |
#### IPTablesProxy NetworkProxy Integration Options
#### NfTablesProxy QoS Options
| Option | Description | Default |
|----------------------|---------------------------------------------------|---------|
| `enabled` | Enable Quality of Service features | false |
| `maxRate` | Maximum bandwidth rate (e.g. "10mbps") | - |
| `priority` | Traffic priority (1-10, 1 is highest) | - |
| `markConnections` | Mark connections for easier management | false |
#### NfTablesProxy NetworkProxy Integration Options
| Option | Description | Default |
|----------------------|---------------------------------------------------|---------|
@ -490,18 +528,30 @@ The `PortProxy` class can inspect the SNI (Server Name Indication) field in TLS
- Domain-specific allowed IP ranges
- Protection against SNI renegotiation attacks
### Enhanced IPTables Management
### Enhanced NfTables Management
The improved `IPTablesProxy` class offers advanced capabilities:
The `NfTablesProxy` class offers advanced capabilities compared to the previous IPTablesProxy:
- Support for multiple port ranges and individual ports
- IPv6 support with ip6tables
- Source IP filtering with allow/block lists
- Custom chain creation for better rule organization
- More efficient IP filtering using nftables sets
- IPv6 support with full feature parity
- Quality of Service (QoS) features including bandwidth limiting and traffic prioritization
- Advanced connection tracking for stateful NAT
- Robust error handling with retry mechanisms
- Structured logging with JSON support
- NetworkProxy integration for SSL termination
- Automatic rule existence checking to prevent duplicates
- Comprehensive cleanup on shutdown
### Port80Handler with Glob Pattern Support
The `Port80Handler` class now includes support for glob pattern domain matching:
- Supports wildcard domains like `*.example.com` for HTTP request routing
- Detects glob patterns and skips certificate issuance for them
- Smart routing that first attempts exact matches, then tries pattern matching
- Supports forwarding HTTP requests to backend services
- Separate forwarding configuration for ACME challenges
## Troubleshooting
### Browser Certificate Errors

2
ts/00_commitinfo_data.ts
View File

@ -3,6 +3,6 @@
*/
export const commitinfo = {
name: '@push.rocks/smartproxy',
version: '5.0.0',
version: '5.1.0',
description: 'A powerful proxy package that effectively handles high traffic, with features such as SSL/TLS support, port proxying, WebSocket handling, dynamic routing with authentication options, and automatic ACME certificate management.'
}