s1d3sw1ped/teleport
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
5165713406987dc229473093d6c962468dbc4a9d
teleport/README.md
Justin Harms 5165713406
All checks were successful
Release Tag / release (push) Successful in 8s
Details
Enhance README with detailed usage and configuration examples 
- Added a new section explaining how Teleport works, including a flow diagram.
- Provided example configurations for both server and client in YAML format.
- Clarified usage scenarios for connecting to remote services through the encrypted tunnel.
2025-09-20 18:38:39 -05:00

523 lines
18 KiB
Markdown
Raw Blame History

# Teleport - Secure Port Forwarding
Teleport is a secure port forwarding tool that allows you to forward ports between different instances with end-to-end encryption.
## How It Works
```
┌─────────────────┐ Encrypted Tunnel ┌─────────────────┐
│ Client A │◄────── Port 9000 ──────►│ Teleport │
│ │ │ Server │
│ │ │ │
│ ┌───────────┐ │ │ ┌───────────┐ │
│ │teleport │ │ │ │teleport │ │
│ │client │ │ │ │server │ │
│ └───────────┘ │ │ └───────────┘ │───────────┐
└─────────────────┘ └─────────────────┘ │
│ │ │
│ Ports 8080,2222 │ Ports 80,22 │
│ (local) │ (targets) │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ User connects │ │ Remote │ │ Remote │
│ to localhost: │ │ Web Server │ │ SSH Server │
│ 8080, 2222 │ │ (192.168.1.100) │ │ (192.168.1.200) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
Flow: User → Client:8080,2222 → Encrypted Tunnel (Port 9000) → Server:80,22 → Remote Services
```
**Note:** The different ports (8080/2222 vs 80/22) are shown for demonstration purposes only. Client and service ports can be identical - teleport will handle the port mapping transparently.
### Example Configuration
**Server Configuration** (`server.yaml`):
```yaml
instance_id: teleport-server-01
listen_address: :9000
remote_address: ""
ports:
- "tcp://192.168.1.100:80"
- "tcp://192.168.1.200:22"
encryption_key: your-secure-encryption-key-here
keep_alive: true
read_timeout: 30s
write_timeout: 30s
```
**Client Configuration** (`client.yaml`):
```yaml
instance_id: teleport-client-01
listen_address: ""
remote_address: server.example.com:9000
ports:
- "tcp://80:8080"
- "tcp://22:2222"
encryption_key: your-secure-encryption-key-here
keep_alive: true
read_timeout: 30s
write_timeout: 30s
```
**Usage**:
- User connects to `localhost:8080` → Traffic flows through encrypted tunnel on port 9000 → Server forwards to remote web server at `192.168.1.100:80`
- User connects to `localhost:2222` → Traffic flows through same encrypted tunnel on port 9000 → Server forwards to remote SSH server at `192.168.1.200:22`
Both services share the same encrypted tunnel connection!
## Features
- **Secure Encryption**: All traffic is encrypted using AES-GCM encryption with PBKDF2 key derivation
- **Port Forwarding**: Forward multiple ports with different protocols (TCP and UDP)
- **Configuration-based**: Easy configuration via YAML files
- **Bidirectional**: Full bidirectional port forwarding
- **Keep-alive**: Connection keep-alive support
- **Protocol Support**: Both TCP and UDP protocols supported
- **Multi-Client Support**: Multiple clients can connect to one server using packet tagging
- **UDP Packet Tagging**: UDP packets are tagged with client IDs for proper routing
- **Built-in DNS Server**: Custom DNS server with configurable records and backup fallback
- **Rate Limiting**: Configurable rate limiting with token bucket algorithm
- **Connection Pooling**: Efficient connection management with pooling
- **Replay Protection**: UDP packet replay attack protection with timestamp validation
- **Advanced Logging**: Sanitized logging with configurable levels, formats, and file output
- **Security Features**: Entropy validation, packet timestamp validation, and secure key generation
## Installation
```bash
# Build the application
go build -o teleport cmd/teleport/main.go
# Or use the pre-built binaries from releases
# Windows: teleport.exe (no console) or teleport-console.exe (with console)
# Linux: teleport
```
## Configuration
Teleport uses YAML configuration files. You need separate configurations for server and client instances.
### Generate Example Configuration
Generate example configuration files:
```bash
# Generate server configuration (filename contains "server")
./teleport --generate-config --config server.yaml
# Generate client configuration
./teleport --generate-config --config client.yaml
# Generate default configuration (client)
./teleport --generate-config
```
### Server Configuration (`server.yaml`)
```yaml
instance_id: teleport-server-01
listen_address: :8080
remote_address: ""
ports:
- "tcp://localhost:80"
encryption_key: your-secure-encryption-key-change-this-to-something-random
keep_alive: true
read_timeout: 30s
write_timeout: 30s
max_connections: 1000
rate_limit:
enabled: true
requests_per_second: 100
burst_size: 200
window_size: 1s
dns_server:
enabled: false
listen_port: 5353
backup_server: 8.8.8.8:53
custom_records: []
```
### Client Configuration (`client.yaml`)
```yaml
instance_id: teleport-client-01
listen_address: ""
remote_address: localhost:8080
ports:
- "tcp://80:8080"
encryption_key: your-secure-encryption-key-change-this-to-something-random
keep_alive: true
read_timeout: 30s
write_timeout: 30s
max_connections: 100
rate_limit:
enabled: true
requests_per_second: 50
burst_size: 100
window_size: 1s
dns_server:
enabled: false
listen_port: 5353
backup_server: 8.8.8.8:53
custom_records:
- name: app.local
type: A
value: 127.0.0.1
ttl: 300
```
## Configuration Fields
- `instance_id`: Unique identifier for this teleport instance
- `listen_address`: Address to listen on (server mode) - format: `host:port`
- `remote_address`: Address of remote teleport server (client mode) - format: `host:port`
- `ports`: Array of port forwarding rules in URL-style format
- **Server format**: `protocol://target:targetport` - forwards to remote target
- **Client format**: `protocol://targetport:localport` - forwards to teleport server's targetport, listens on localport
- Examples:
- `"tcp://localhost:80"` (server) - listen on port 80, forward to localhost:80
- `"tcp://server-a:22"` (server) - listen on port 22, forward to server-a:22
- `"tcp://80:8080"` (client) - listen on port 8080, forward to teleport server's port 80
- `"udp://53:5353"` (client) - listen on port 5353, forward to teleport server's port 53
- `encryption_key`: Shared secret key for encryption (must be the same on both sides)
- `keep_alive`: Enable TCP keep-alive
- `read_timeout`: Read timeout duration
- `write_timeout`: Write timeout duration
- `max_connections`: Maximum concurrent connections (default: 1000 for server, 100 for client)
- `rate_limit`: Rate limiting configuration
- `enabled`: Enable rate limiting
- `requests_per_second`: Maximum requests per second
- `burst_size`: Maximum burst size
- `window_size`: Time window for rate limiting
- `dns_server`: DNS server configuration
- `enabled`: Enable built-in DNS server
- `listen_port`: Port for DNS server to listen on
- `backup_server`: Backup DNS server for fallback (e.g., "8.8.8.8:53")
- `custom_records`: Array of custom DNS records
- `name`: Domain name (e.g., "example.com")
- `type`: Record type ("A", "AAAA", "CNAME", "MX", "TXT", "SRV", "NS")
- `value`: Record value (IP address, domain name, or text)
- `ttl`: Time to live in seconds
- `priority`: Priority for MX and SRV records (optional)
- `weight`: Weight for SRV records (optional)
- `port`: Port for SRV records (optional)
## Quick Start
1. **Generate a secure encryption key:**
```bash
./teleport --generate-key
```
2. **Generate configuration files:**
```bash
./teleport --generate-config --config server.yaml
./teleport --generate-config --config client.yaml
```
3. **Edit the configs** and replace the encryption key with the one you generated
4. **Start the server:**
```bash
./teleport --config server.yaml
```
5. **Start the client:**
```bash
./teleport --config client.yaml
```
## Usage
### Start Server
```bash
./teleport --config server.yaml
```
### Start Client
```bash
./teleport --config client.yaml
```
### Show Version
```bash
./teleport --version
# or
./teleport -v
```
### Generate Random Encryption Key
```bash
./teleport --generate-key
# or
./teleport -k
```
This generates a cryptographically secure 256-bit encryption key that you can use in your configuration files.
### Logging Options
```bash
# Set log level (debug, info, warn, error)
./teleport --config config.yaml --log-level debug
# Set log format (text, json)
./teleport --config config.yaml --log-format json
# Set log file
./teleport --config config.yaml --log-file /var/log/teleport.log
```
### Port Format
Teleport uses URL-style port mapping format for cleaner configuration:
```yaml
ports:
- "tcp://80:8080" # Listen on port 8080, forward to teleport server's port 80
- "udp://53:5353" # Listen on port 5353, forward to teleport server's port 53
- "tcp://22:2222" # Listen on port 2222, forward to teleport server's port 22
```
**Format**:
- **Server**: `"protocol://target:targetport"` - listen on targetport, forward to target:targetport
- **Client**: `"protocol://targetport:localport"` - listen on localport, forward to teleport server's targetport
**Examples:**
```yaml
# Server configurations
ports:
- "tcp://localhost:80" # Listen on port 80, forward to localhost:80
- "tcp://server-a:22" # Listen on port 22, forward to server-a:22
- "udp://dns-server:53" # Listen on port 53, forward to dns-server:53
# Client configurations
ports:
- "tcp://80:8080" # Listen on port 8080, forward to teleport server's port 80
- "tcp://22:2222" # Listen on port 2222, forward to teleport server's port 22
- "udp://53:5353" # Listen on port 5353, forward to teleport server's port 53
```
**Example: Remote SSH Access**
To access SSH on Server A through teleport server on Server B:
**Server B configuration:**
```yaml
instance_id: teleport-server-b
listen_address: :8080
remote_address: ""
ports:
- "tcp://server-a:22" # Listen on port 22, forward to server-a:22
encryption_key: your-shared-key
```
**Client C configuration:**
```yaml
instance_id: teleport-client-c
listen_address: ""
remote_address: server-b:8080
ports:
- "tcp://22:2222" # Listen on local port 2222, forward to teleport server's port 22
encryption_key: your-shared-key
```
Then connect from Client C: `ssh user@localhost -p 2222`
### Configuration-Based Mode Detection
The mode (server or client) is automatically determined from the configuration:
- **Server Mode**: When `listen_address` is set and `remote_address` is empty
- **Client Mode**: When `remote_address` is set and `listen_address` is empty
**Important**: The configuration must be clearly either a server or client - you cannot have both `listen_address` and `remote_address` set, and you must have at least one of them set.
### Configuration Validation
The program validates your configuration and will show clear error messages if:
- **Both addresses set**: You have both `listen_address` and `remote_address` configured
- **Neither address set**: You have neither `listen_address` nor `remote_address` configured
**Valid Server Configuration:**
```yaml
listen_address: :8080
remote_address: ""
ports:
- "tcp://localhost:22"
```
**Valid Client Configuration:**
```yaml
listen_address: ""
remote_address: server:8080
ports:
- "tcp://22:2222"
```
## Security
- All traffic is encrypted using AES-GCM encryption with PBKDF2 key derivation
- The encryption key is derived from the provided key using PBKDF2 with 100,000 iterations
- Each connection uses a unique nonce for encryption
- Connection authentication is implicit through successful decryption
- UDP packets include replay protection with timestamp validation
- Encryption keys are validated for entropy and strength
- Logging includes automatic sanitization of sensitive data
- Rate limiting prevents abuse and DoS attacks
## Example Use Cases
1. **SSH Tunneling**: Forward SSH connections through a secure tunnel
2. **Database Access**: Securely access remote databases
3. **Web Services**: Forward HTTP/HTTPS traffic
4. **DNS Services**: Forward DNS queries (UDP port 53)
5. **NTP Services**: Forward time synchronization (UDP port 123)
6. **SNMP Monitoring**: Forward SNMP queries (UDP port 161)
7. **Custom Services**: Forward any TCP or UDP-based service
8. **Local DNS Resolution**: Serve custom DNS records for local development
9. **DNS Override**: Override specific domains with custom IP addresses
10. **Service Discovery**: Use SRV records for service discovery and load balancing
## Example Setup
1. **Server Side** (where services are running):
- Generate: `./teleport -generate-config -config teleport-server.yaml`
- Edit the configuration file with the services you want to expose
- Run: `./teleport -config teleport-server.yaml`
2. **Client Side** (where you want to access services):
- Generate: `./teleport -generate-config -config teleport-client.yaml`
- Edit the configuration file with local ports and remote server address
- Run: `./teleport -config teleport-client.yaml`
- Connect to `localhost:local_port` to access the remote service
## Multi-Client Support
Multiple clients can connect to the same server using packet tagging:
1. **Start Server**: `./teleport -config teleport-server.yaml`
2. **Start Client 1**: `./teleport -config teleport-client.yaml`
3. **Start Client 2**: `./teleport -config teleport-client2.yaml`
Both clients can use the same local ports (e.g., 5353 for DNS) because:
- Each client has a unique `instance_id` in their config
- UDP packets are tagged with the client ID
- Server routes responses back to the correct client
- No port conflicts between multiple clients
## DNS Server Features
The built-in DNS server provides:
### Custom DNS Records
- **A Records**: Map domain names to IPv4 addresses
- **AAAA Records**: Map domain names to IPv6 addresses
- **CNAME Records**: Create domain aliases
- **MX Records**: Mail server configuration
- **TXT Records**: Text-based records
- **SRV Records**: Service discovery records
- **NS Records**: Name server records
### Example DNS Configuration
```yaml
dns_server:
enabled: true
listen_port: 5353
backup_server: 8.8.8.8:53
custom_records:
- name: api.local
type: A
value: 192.168.1.100
ttl: 300
- name: www.local
type: CNAME
value: api.local
ttl: 300
- name: _http._tcp.api.local
type: SRV
value: api.local
ttl: 300
priority: 10
weight: 5
port: 8080
- name: _mysql._tcp.db.local
type: SRV
value: db.local
ttl: 300
priority: 10
weight: 1
port: 3306
```
### DNS Usage
```bash
# Test custom DNS records
nslookup api.local localhost -port=5353
nslookup www.local localhost -port=5353
# Test SRV records for service discovery
nslookup -type=SRV _http._tcp.api.local localhost -port=5353
nslookup -type=SRV _mysql._tcp.db.local localhost -port=5353
# Fallback to backup server for unknown domains
nslookup google.com localhost -port=5353
```
## Binary Names
The application provides different binaries for different use cases:
- **`teleport`**: Main binary (Windows: no console window, Linux: standard)
- **`teleport-console`**: Console version (Windows: shows console window)
## Advanced Features
### Rate Limiting
Teleport includes configurable rate limiting to prevent abuse:
```yaml
rate_limit:
enabled: true
requests_per_second: 100 # Maximum requests per second
burst_size: 200 # Maximum burst size
window_size: 1s # Time window for rate limiting
```
### Advanced Logging
Teleport includes sophisticated logging with:
- Configurable log levels (debug, info, warn, error)
- Multiple output formats (text, JSON)
- File and console output support
- Automatic sanitization of sensitive data (keys, passwords, tokens)
- Secure file permissions (owner read/write only)
### Connection Management
- **Connection Pooling**: Efficient connection reuse for better performance
- **Connection Limits**: Configurable maximum concurrent connections
- **Health Checks**: Automatic detection and cleanup of dead connections
- **Graceful Shutdown**: Proper cleanup of resources on exit
## Notes
- The encryption key must be identical on both server and client
- Use `./teleport --generate-key` to create a secure random encryption key
- The server listens on the specified `listen_address` for incoming connections
- The client connects to the remote server and forwards local connections
- All port forwarding is bidirectional
- Port format uses URL-style conventions: `"protocol://target:port"`
- Configuration files use YAML format for better readability
- The application automatically detects server vs client mode based on configuration
- UDP packets include replay protection and timestamp validation
- All sensitive data in logs is automatically sanitized
- Rate limiting helps prevent abuse and DoS attacks
- Connection pooling improves performance for high-traffic scenarios
Reference in New Issue View Git Blame Copy Permalink