# 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