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

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:

   UNIFI_USERNAME=automation
   UNIFI_PASSWORD="your-password"
   

---

Script: Configure Static Route

Location

scripts/unifi/configure-static-route-playwright.js

Usage

Dry Run (Test Mode)

cd /home/intlc/projects/proxmox
DRY_RUN=true HEADLESS=true node scripts/unifi/configure-static-route-playwright.js

Actual Configuration

cd /home/intlc/projects/proxmox
HEADLESS=true node scripts/unifi/configure-static-route-playwright.js

With Visible Browser (Debugging)

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 - API limitations
• UDM_PRO_ROUTING_API_LIMITATIONS.md - Routing API limitations
• UDM_PRO_AUTOMATION_COMPLETE_GUIDE.md - Automation and options

---

Last Updated: 2026-01-14