proxmox/docs/04-configuration/UDM_PRO_BROWSER_AUTOMATION_GUIDE.md

# UDM Pro Browser Automation Guide

**Last Updated:** 2026-01-14  
**Status:** Active Documentation
**Purpose:** Configure static routes and other settings via browser automation when API is unavailable

---

## Overview

This guide documents the browser automation solution for configuring UDM Pro settings that are not available via the API, such as:
- Static Routes
- Network/VLAN creation (if Private API fails)
- DHCP Reservations
- Port Profiles

---

## Prerequisites

### 1. Install Playwright

```bash
cd /home/intlc/projects/proxmox
pnpm add -D -w playwright@latest
pnpm exec playwright install chromium
```

### 2. Account Requirements

**IMPORTANT:** The account used for browser automation must:
- ✅ Be a **local admin account** (not SSO/cloud account)
- ✅ Have **2FA disabled** (browser automation cannot handle 2FA)
- ✅ Have **full network management permissions**

**Current Status:**
- `nsatoshi2007`: ❌ Authentication fails (likely 2FA/SSO enabled)
- `unifi_api`: ⚠️ May work if 2FA is disabled

**Solution:** Create a dedicated local admin account for automation:
1. Access UDM Pro web UI: `https://192.168.0.1`
2. Navigate to **Settings** → **System Settings** → **Users**
3. Create new local admin account:
   - Username: `automation` (or your choice)
   - Password: (strong password)
   - Role: **Full Admin**
   - **Important:** Ensure it's local (not SSO)
   - **Important:** Do NOT enable 2FA
4. Update `~/.env`:
   ```bash
   UNIFI_USERNAME=automation
   UNIFI_PASSWORD="your-password"
   ```

---

## Script: Configure Static Route

### Location
`scripts/unifi/configure-static-route-playwright.js`

### Usage

#### Dry Run (Test Mode)
```bash
cd /home/intlc/projects/proxmox
DRY_RUN=true HEADLESS=true node scripts/unifi/configure-static-route-playwright.js
```

#### Actual Configuration
```bash
cd /home/intlc/projects/proxmox
HEADLESS=true node scripts/unifi/configure-static-route-playwright.js
```

#### With Visible Browser (Debugging)
```bash
cd /home/intlc/projects/proxmox
HEADLESS=false node scripts/unifi/configure-static-route-playwright.js
```

### Configuration

The script is configured to create a static route:
- **Name:** Route to VLAN 11
- **Destination:** `192.168.11.0/24`
- **Gateway:** `192.168.11.1`

To modify, edit the `ROUTE_CONFIG` object in the script.

### Features

✅ **Step-by-step navigation** with verification  
✅ **Error handling** and retry logic  
✅ **Screenshot capture** for debugging (saved to `scripts/unifi/screenshots/`)  
✅ **Dry-run mode** for testing  
✅ **Detailed logging** at each step  
✅ **Multiple selector strategies** for UI elements (handles UI changes)

### Screenshots

Screenshots are automatically saved to `scripts/unifi/screenshots/` with timestamps:
- `01-login-page.png` - Initial login page
- `02-credentials-filled.png` - After filling credentials
- `03-after-login.png` - After successful login
- `04-routing-page.png` - Routing settings page
- `05-static-routes-page.png` - Static routes section
- `06-before-add-button.png` - Before clicking Add
- `07-form-filled.png` - After filling route form
- `08-route-saved.png` - After saving route
- `error-state.png` - If an error occurs

---

## Troubleshooting

### Authentication Fails (403 Error)

**Symptoms:**
- Login returns 403 Forbidden
- Script gets redirected back to login page
- Error: "Login failed - still on login page"

**Causes:**
1. Account has 2FA enabled
2. Account is SSO/cloud-only (not local)
3. Wrong password
4. Account is disabled or locked

**Solutions:**
1. Create a new local admin account without 2FA (see Prerequisites)
2. Verify password in `~/.env`
3. Check account status in UDM Pro web UI
4. Try logging in manually with the same credentials

### Cannot Find Add Button

**Symptoms:**
- Script reaches static routes page
- Cannot find "Add" or "Create" button
- Error: "Could not find Add/Create button"

**Causes:**
1. UI structure changed
2. Not on the correct page
3. Button has different text/selector

**Solutions:**
1. Check screenshots in `scripts/unifi/screenshots/`
2. Run with `HEADLESS=false` to see what's happening
3. Manually verify the static routes page in browser
4. Update selectors in script if UI changed

### Navigation Fails

**Symptoms:**
- Cannot navigate to Settings or Routing page
- Gets redirected to login repeatedly

**Causes:**
1. Authentication not properly established
2. URL structure changed
3. Session expired

**Solutions:**
1. Verify login succeeded (check screenshots)
2. Try manual navigation to verify URL structure
3. Update navigation URLs in script if needed

---

## Current Status

### ✅ Completed
- Playwright installed and configured
- Script created with comprehensive error handling
- Screenshot capture for debugging
- Dry-run mode for testing
- Multiple selector strategies

### ⚠️ Pending
- **Authentication Issue:** Current account (`nsatoshi2007`) fails with 403
  - **Action Required:** Create local admin account without 2FA
  - **Alternative:** Disable 2FA on existing account (if possible)

### 🔄 Next Steps
1. Create local admin account for automation
2. Update `~/.env` with new credentials
3. Test script in dry-run mode
4. Run script to configure static route
5. Verify route was created in UDM Pro web UI

---

## Manual Alternative

If browser automation continues to have issues, you can manually configure the static route:

1. **Access UDM Pro:** `https://192.168.0.1`
2. **Navigate to:** Settings → Routing & Firewall → Static Routes
3. **Click:** Add (or Create)
4. **Fill in:**
   - **Name:** Route to VLAN 11
   - **Destination Network:** `192.168.11.0/24`
   - **Gateway:** `192.168.11.1`
5. **Click:** Save

---

## Related Documentation

- [UDM_PRO_API_LIMITATIONS.md](./UDM_PRO_API_LIMITATIONS.md) - API limitations
- [UDM_PRO_ROUTING_API_LIMITATIONS.md](./UDM_PRO_ROUTING_API_LIMITATIONS.md) - Routing API limitations
- [UDM_PRO_AUTOMATION_COMPLETE_GUIDE.md](UDM_PRO_AUTOMATION_COMPLETE_GUIDE.md) - Automation and options

---

**Last Updated:** 2026-01-14