proxmox/docs/04-configuration/UDM_PRO_FIREWALL_API_LIMITATIONS.md

UDM Pro Firewall API Limitations

Last Updated: 2025-01-20
Status: API Limitations Discovered

---

Overview

While the UniFi Network API provides ACL Rules endpoints for firewall configuration, there are limitations when attempting to block inter-VLAN traffic between overlapping network sets.

---

Issue: Blocking Inter-VLAN Traffic

Problem

When attempting to create an ACL rule that blocks traffic between multiple VLANs (e.g., VLANs 200-203 for sovereign tenant isolation), the API returns:

{
  "statusCode": 400,
  "statusName": "BAD_REQUEST",
  "code": "api.acl-rule.validation.blocking-traffic-in-same-subnet",
  "message": "Blocking traffic in the same subnet (source 10.203.0.1/20, destination 10.203.0.1/20) with IP ACL rules is not supported"
}

Root Cause

The API interprets ACL rules with overlapping source and destination network sets as blocking traffic within the same subnet, which it doesn't support. This occurs even when the intent is to block traffic between different VLANs, not within each VLAN.

Example: Sovereign Tenant Isolation

Goal: Block east-west traffic between VLANs 200-203 (sovereign tenants)

Attempted Configuration:

{
  "type": "IPV4",
  "action": "BLOCK",
  "sourceFilter": {
    "type": "NETWORKS",
    "networkIds": [
      "vlan-200-id",
      "vlan-201-id",
      "vlan-202-id",
      "vlan-203-id"
    ]
  },
  "destinationFilter": {
    "type": "NETWORKS",
    "networkIds": [
      "vlan-200-id",
      "vlan-201-id",
      "vlan-202-id",
      "vlan-203-id"
    ]
  }
}

Result: ❌ API Error - "Blocking traffic in the same subnet is not supported"

---

Potential Solutions

Option 1: Network-Level Isolation (if available)

Some UniFi configurations support network-level isolation flags:

• isolationEnabled: Network-level isolation setting
• May need to be configured via Network Update API endpoint
• Check if PUT /v1/sites/{siteId}/networks/{networkId} supports isolation settings

Option 2: Individual Pair Rules (Complex)

Create separate ACL rules for each pair of VLANs:

• Block VLAN 200 → VLANs 201, 202, 203
• Block VLAN 201 → VLANs 200, 202, 203
• Block VLAN 202 → VLANs 200, 201, 203
• Block VLAN 203 → VLANs 200, 201, 202

Limitations:

• Requires 12 rules (4 × 3 pairs)
• More complex to manage
• Still may hit API limitations

Option 3: Firewall Zones (if supported)

Use Firewall Zones to group networks and apply policies:

• Create a zone for sovereign tenants
• Apply zone-level policies
• May require different API approach

Option 4: Manual Configuration (Recommended for now)

Configure firewall rules via web UI:

1. Access UniFi Network web interface
2. Navigate to Settings → Firewall & Security
3. Configure rules manually with proper source/destination settings
4. The web UI may have different validation rules than the API

---

What Works via API

✅ Allow Rules (Source → Destination)

Rules that allow traffic between specific VLANs work correctly:

• Management VLAN (11) → Service VLANs
• Service VLANs → Management VLAN (monitoring)
• Specific port-based rules

✅ Single Network Rules

Rules targeting single networks (not overlapping sets) work:

• Block specific network → all other networks
• Allow specific network → specific destination

---

Testing Results

Tested Endpoints

1. ACL Rules List: ✅ Working

   • GET /v1/sites/{siteId}/acl-rules

2. ACL Rules Create: ⚠️ Limited

   • POST /v1/sites/{siteId}/acl-rules
   • Works for allow rules and non-overlapping blocks
   • Doesn't support overlapping source/destination blocks

3. Network Isolation: ⏳ Untested

   • Network objects have isolationEnabled field
   • Update endpoint may support this
   • Requires further testing

---

Recommendations

For Sovereign Tenant Isolation

Current Status: ❌ Cannot be automated via API (with overlapping networks)

Recommended Approach:

1. Manual Configuration (Short-term):

   • Use UniFi Network web UI
   • Configure firewall rules manually
   • Document the configuration

2. Alternative Approaches (Future):

   • Test network-level isolationEnabled flag via API
   • Create individual pair rules (if API allows)
   • Wait for API updates that support this use case

For Other Firewall Rules

Management VLAN Access: ✅ Can be automated

• Allow VLAN 11 → Service VLANs (specific ports)
• Use non-overlapping source/destination

Monitoring Access: ✅ Can be automated

• Allow Service VLANs → VLAN 11 (monitoring ports)
• Use non-overlapping source/destination

---

Next Steps

1. Test Network-Level Isolation:

   • Try updating network isolationEnabled flag via API
   • Test if this achieves the desired isolation

2. Test Individual Pair Rules:

   • Create rules for specific VLAN pairs
   • Verify if API accepts these

3. Document Manual Configuration:

   • Create step-by-step guide for web UI configuration
   • Document the exact rules needed

4. Monitor API Updates:

   • Check for future API versions that support this use case
   • Review API documentation updates

---

Related Documentation

• UDM_PRO_API_FIREWALL_ENDPOINTS.md - Firewall API endpoints documentation
• UDM_PRO_STATUS.md - Configuration status
• UniFi Network API Documentation - Official API documentation

---

Last Updated: 2025-01-20