# Network Configuration

Gaol provides comprehensive network configuration options including basic networking, VPN tunnels, Tor privacy routing, and WireGuard mesh networks.

## Basic Network Configuration

**Network Modes** (`specs/models.py` - SpecNetwork):
- `shared` (default): NAT through host
- `bridged`: Direct network access with own IP
- `host`: Share host network namespace
- `none`: No networking

**Port Mapping**: `["8080:80", "53:53/udp", "0.0.0.0:8443:443/tcp"]`

---

## VPN Configuration

Location: `privacy/vpn/`

**VPNGatewayConfig**:
| Field | Description | Default |
|-------|-------------|---------|
| `provider` | `openvpn` or `wireguard` | - |
| `config_file` | Path to VPN config (.ovpn or .conf) | - |
| `kill_switch` | Block traffic if VPN drops | `true` |
| `dns_servers` | DNS to use when connected | `["1.1.1.1", "1.0.0.1"]` |
| `route_all_traffic` | Route all container traffic through VPN | `true` |

---

## Tor Configuration

Location: `privacy/tor/`

### Tor Proxy

**TorProxyConfig**:
| Field | Description | Default |
|-------|-------------|---------|
| `socks_port` | SOCKS5 proxy port | `9050` |
| `control_port` | Tor control port | `9051` |
| `dns_port` | DNS resolution port | `5353` |
| `trans_port` | Transparent proxy port | `9040` |
| `transparent` | Enable transparent proxy mode | `false` |
| `exit_nodes` | Preferred exit countries (e.g., `['US', 'DE']`) | `[]` |
| `exclude_nodes` | Countries to avoid | `[]` |
| `bridge_enabled` | Use bridges for censored networks | `false` |
| `bridges` | Bridge addresses | `[]` |
| `strict_nodes` | Strictly enforce exit/exclude preferences | `false` |

### Hidden Services

Expose containers as .onion addresses:

**HiddenServiceConfig**:
| Field | Description | Default |
|-------|-------------|---------|
| `name` | Unique hidden service name | - |
| `container_name` | Container to expose | - |
| `container_port` | Port in container to expose | - |
| `hidden_service_port` | Port on .onion address | `80` |
| `version` | Hidden service version (2 or 3) | `3` |

---

## WireGuard Mesh

Location: `privacy/wireguard/`

**WireGuardMeshConfig**:
| Field | Description | Default |
|-------|-------------|---------|
| `name` | Unique mesh network name | - |
| `subnet` | Mesh network subnet | `10.200.0.0/24` |
| `interface_name` | WireGuard interface name | `wg0` |
| `listen_port` | UDP port | `51820` |
| `peers` | List of peer configurations | `[]` |

**WireGuardPeer**:
| Field | Description | Default |
|-------|-------------|---------|
| `name` | Peer identification name | - |
| `public_key` | Peer's public key | - |
| `endpoint` | Peer endpoint (host:port) | - |
| `allowed_ips` | IP ranges to route through peer | `["0.0.0.0/0"]` |
| `persistent_keepalive` | Keepalive interval (seconds) | `25` |
| `preshared_key` | Optional additional security key | - |

---

## Dev Tunnels

Location: `tunnel/`

Expose local containers to the internet via Cloudflare tunnels.

**TunnelConfig**:
| Field | Description |
|-------|-------------|
| `container_name` | Container to tunnel |
| `container_port` | Port to expose |
| `host_port` | Port on host (optional) |
| `protocol` | `http`, `https`, or `tcp` |

Returns public URL like `https://xxx.trycloudflare.com`

---

## DNS Leak Prevention

**DNSLeakConfig**:
| Field | Description | Default |
|-------|-------------|---------|
| `enabled` | Enable DNS leak prevention | `true` |
| `dns_servers` | Allowed DNS servers | `[]` |
| `block_direct_dns` | Block non-allowed DNS | `true` |
| `allow_local` | Allow local resolver (127.0.0.1) | `false` |

---

## Bridge Networking

Location: `networking/bridge.py`

**BridgeConfig**:
| Field | Description | Default |
|-------|-------------|---------|
| `name` | Bridge interface name | `br0` |
| `ip_address` | Bridge IP with CIDR | - |
| `dhcp_enabled` | Enable DHCP on bridge | `false` |
| `nat_enabled` | Enable NAT | `true` |
| `ipv6_enabled` | Enable IPv6 | `false` |
| `ipv6_address` | IPv6 address with CIDR | - |

---

## Privacy Modes

| Mode | Description |
|------|-------------|
| `NONE` | No privacy routing |
| `TOR_PROXY` | SOCKS proxy through Tor |
| `TOR_TRANSPARENT` | Transparent Tor proxy (all traffic) |
| `VPN` | VPN gateway routing |
| `WIREGUARD` | WireGuard mesh routing |

---

## Firewall Management

Location: `networking/firewall.py`

Supports both `iptables` and `nftables` backends with auto-detection.

**ForwardingRule**:
| Field | Description |
|-------|-------------|
| `host_port` | Port on host |
| `guest_ip` | Container IP |
| `guest_port` | Port in container |
| `protocol` | TCP or UDP |
| `host_ip` | Bind address (default: `0.0.0.0`) |

---

## Container Group Networking

Location: `groups/networking.py`

Containers in a group can reach each other by name using shared bridge networks.

- Network prefix: `gaol-{group_name}`
- Private range: `172.30.0.0/16`
- Automatic DNS aliases for service discovery

---

## Spec File Privacy Configuration

Privacy features can be configured directly in spec files for one-command deployment.

### Example: Tor Browser with Exit Node Preferences

```yaml
# specs/tor-browser.yaml
name: tor-browser
runtime: nspawn
distro: trixie
profiles:
  - gui
  - firefox-wayland

privacy:
  tor:
    enabled: true
    transparent: true         # Route ALL traffic through Tor
    exit_nodes: [SE, DE]      # Sweden, Germany only
    exclude_nodes: [RU, CN]   # Never use Russia, China
```

```bash
gaol apply specs/tor-browser.yaml --start
```

### Example: Mullvad VPN Browser

```yaml
# specs/mullvad-browser.yaml
name: mullvad-browser
runtime: nspawn
distro: trixie
profiles:
  - gui
  - firefox-wayland

privacy:
  vpn:
    enabled: true
    provider: wireguard
    config_file: ~/mullvad-wg.conf
    kill_switch: true
    dns_servers: [10.64.0.1]  # Mullvad DNS
```

### Example: Tor Hidden Service

```yaml
# specs/onion-webserver.yaml
name: onion-webserver
runtime: nspawn
distro: trixie
profiles:
  - base

privacy:
  onion:
    enabled: true
    port: 80            # Container port
    onion_port: 80      # .onion port
    version: 3          # v3 onion (recommended)
```

### Example: Cloudflare Tunnel

```yaml
# specs/tunnel-webserver.yaml
name: tunnel-webserver
runtime: nspawn
distro: trixie
profiles:
  - base

privacy:
  tunnel:
    enabled: true
    port: 80
    protocol: http
```

---

## CLI Examples

### Tor Proxy Management

```bash
# Create Tor proxy for a container
gaol network tor-proxy create mytor --container myapp

# Transparent proxy (routes ALL traffic including DNS)
gaol network tor-proxy create mytor -c myapp --transparent

# With exit node preferences
gaol network tor-proxy create mytor -c myapp --exit SE --exit DE

# List proxies
gaol network tor-proxy list

# Check status
gaol network tor-proxy status mytor

# Delete proxy
gaol network tor-proxy delete mytor
```

### Tor Hidden Services

```bash
# Create hidden service exposing container port
gaol network onion create myservice --container nginx --port 80

# Get the .onion address
gaol network onion address myservice

# List hidden services
gaol network onion list

# Delete hidden service
gaol network onion delete myservice
```

### VPN Gateway

```bash
# Create VPN with WireGuard
gaol network vpn-gateway create myvpn \
  --config ~/mullvad-wg.conf \
  --provider wireguard \
  --kill-switch

# Create VPN with OpenVPN
gaol network vpn-gateway create myvpn \
  --config ~/vpn.ovpn \
  --provider openvpn

# Disable kill switch
gaol network vpn-gateway create myvpn \
  --config ~/vpn.conf \
  --provider wireguard \
  --no-kill-switch

# Check status
gaol network vpn-gateway status myvpn

# List gateways
gaol network vpn-gateway list

# Delete gateway
gaol network vpn-gateway delete myvpn
```

### Cloudflare Tunnels

```bash
# Start tunnel for container port
gaol tunnel start mycontainer 8080

# Start with specific host port
gaol tunnel start mycontainer 3000 --host-port 3001

# List active tunnels
gaol tunnel list

# Stop a tunnel
gaol tunnel stop <tunnel-id>

# Stop all tunnels
gaol tunnel stop-all

# Stop tunnels for specific container
gaol tunnel stop-all --container myapp
```

---

## Quick Reference

| Task | Spec Config | CLI Command |
|------|-------------|-------------|
| Tor SOCKS proxy | `privacy.tor.enabled: true` | `network tor-proxy create` |
| Transparent Tor | `privacy.tor.transparent: true` | `... --transparent` |
| Exit node filter | `privacy.tor.exit_nodes: [US, DE]` | `... --exit US --exit DE` |
| .onion service | `privacy.onion.port: 80` | `network onion create` |
| WireGuard VPN | `privacy.vpn.provider: wireguard` | `network vpn-gateway create --provider wireguard` |
| OpenVPN | `privacy.vpn.provider: openvpn` | `... --provider openvpn` |
| Kill switch | `privacy.vpn.kill_switch: true` | `... --kill-switch` |
| Public tunnel | `privacy.tunnel.port: 80` | `tunnel start container 80` |
