explorer-monorepo/UDM_PRO_SSH_ACCESS_GUIDE.md

# UDM Pro SSH Access Guide

**Date**: 2026-01-21  
**Purpose**: Access UDM Pro via SSH to diagnose and fix firewall/port forwarding issues

---

## SSH Access to UDM Pro

### Enable SSH (If Not Already Enabled)

1. **Via Web UI:**
   - Navigate to UDM Pro web interface
   - Go to **Settings** → **System Settings** → **Advanced Features**
   - Enable **SSH** (toggle ON)
   - Note: SSH is typically enabled by default

2. **Default Credentials:**
   - **Username**: `root`
   - **Password**: Your UDM Pro admin password (same as web UI)

### Common UDM Pro IP Addresses

- **192.168.11.1** - If on MGMT-LAN network
- **192.168.1.1** - Default network
- **192.168.0.1** - Alternative default

---

## UDM Pro CLI Commands

### Check System Information

```bash
# System info
uname -a

# UDM Pro version
cat /usr/lib/version

# Network interfaces
ip addr show
```

### Check Firewall Rules

```bash
# View iptables rules (if accessible)
iptables -L -n -v

# View NAT rules
iptables -t nat -L -n -v

# View firewall configuration files
ls -la /mnt/data/udapi-config/
```

### Check Port Forwarding

```bash
# View port forwarding rules (if in config)
cat /mnt/data/udapi-config/firewall.json

# Or check UniFi config
cat /mnt/data/unifi/config/config.gateway.json
```

### UniFi Controller Commands

```bash
# Access UniFi CLI
unifi-os shell

# Or directly
mca-ctrl -t dump-cfg
```

---

## Limitations of UDM Pro SSH

### What We CAN Do:

1. **View Configuration:**
   - Check firewall rules
   - View port forwarding configuration
   - Check network interfaces
   - View logs

2. **Diagnose Issues:**
   - Verify rule order
   - Check if rules are active
   - View firewall logs
   - Check network routing

### What We CANNOT Do (Easily):

1. **Direct Rule Modification:**
   - UDM Pro uses UniFi Controller for configuration
   - Changes via CLI may not persist
   - Best to use web UI for changes

2. **Firewall Rule Editing:**
   - Rules are managed by UniFi Controller
   - CLI changes may be overwritten
   - Web UI is the authoritative source

---

## Recommended Approach

### Step 1: SSH and Diagnose

```bash
# SSH to UDM Pro
ssh root@192.168.11.1  # or your UDM Pro IP

# Check firewall rules
iptables -L -n -v | grep -A 10 "76.53.10.36"
iptables -t nat -L -n -v | grep -A 10 "76.53.10.36"

# Check port forwarding
cat /mnt/data/udapi-config/firewall.json | grep -A 5 "76.53.10.36"
```

### Step 2: View Configuration Files

```bash
# UniFi config
cat /mnt/data/unifi/config/config.gateway.json

# Firewall config
cat /mnt/data/udapi-config/firewall.json

# Network config
cat /mnt/data/udapi-config/network.json
```

### Step 3: Check Logs

```bash
# Firewall logs
tail -f /var/log/messages | grep firewall

# Or UniFi logs
tail -f /mnt/data/unifi/logs/server.log
```

### Step 4: Make Changes via Web UI

**After diagnosing via SSH, make changes via Web UI:**
- More reliable
- Changes persist
- Easier to verify

---

## Alternative: UniFi API

If SSH access is limited, we can use the UniFi API:

```bash
# UniFi API endpoints
# https://<UDM_IP>:443/api/
# Requires authentication token
```

---

## What We Can Check via SSH

### 1. Verify Port Forwarding Rules Are Active

```bash
# Check NAT table for port forwarding
iptables -t nat -L -n -v | grep "76.53.10.36"
```

**Expected Output:**
```
DNAT tcp -- 0.0.0.0/0 76.53.10.36 tcp dpt:80 to:192.168.11.166:80
DNAT tcp -- 0.0.0.0/0 76.53.10.36 tcp dpt:443 to:192.168.11.166:443
```

### 2. Check Firewall Rules

```bash
# Check if firewall is blocking
iptables -L -n -v | grep "192.168.11.166"
```

### 3. Verify Rule Order

```bash
# List all firewall rules in order
iptables -L -n --line-numbers
```

### 4. Check Network Interfaces

```bash
# Verify WAN interface
ip addr show | grep "76.53.10"
```

---

## Making Changes

### Option 1: Via Web UI (Recommended)

1. SSH to diagnose the issue
2. Note what needs to be changed
3. Make changes via Web UI
4. Verify via SSH again

### Option 2: Via CLI (Advanced)

**Warning**: CLI changes may not persist or may be overwritten by UniFi Controller.

```bash
# Example: Add firewall rule (may not persist)
iptables -I FORWARD -s 0.0.0.0/0 -d 192.168.11.166 -p tcp --dport 80 -j ACCEPT
iptables -I FORWARD -s 0.0.0.0/0 -d 192.168.11.166 -p tcp --dport 443 -j ACCEPT
```

---

## Testing After SSH Diagnosis

Once we identify the issue via SSH:

1. **If rules are missing**: Add via Web UI
2. **If rules are disabled**: Enable via Web UI
3. **If rule order is wrong**: Reorder via Web UI
4. **If firewall is blocking**: Add allow rule via Web UI

---

## Summary

**SSH Access Benefits:**
- ✅ View current configuration
- ✅ Diagnose firewall/port forwarding issues
- ✅ Check rule order and status
- ✅ View logs

**SSH Limitations:**
- ⚠️ Changes via CLI may not persist
- ⚠️ Web UI is authoritative source
- ⚠️ Best to use Web UI for changes

**Recommended Workflow:**
1. SSH to diagnose
2. Identify the issue
3. Make changes via Web UI
4. Verify via SSH

---

**Next Step**: SSH to UDM Pro and check firewall/port forwarding configuration