proxmox/docs/04-configuration/UDM_PRO_API_FIREWALL_ENDPOINTS.md

UDM Pro Firewall/ACL API Endpoints

Last Updated: 2025-01-20
Status: Active Documentation API Documentation: UniFi Network API Documentation

---

Overview

The Official UniFi Network API provides comprehensive firewall and access control configuration through ACL Rules (Access Control List rules). These endpoints allow programmatic configuration of firewall policies, network segmentation, and traffic filtering.

Base URL: https://192.168.0.1/proxy/network/integration/v1/
Authentication: X-API-KEY header
Site ID: 88f7af54-98f8-306a-a1c7-c9349722b1f6

---

Available Firewall/ACL Endpoints

1. ACL Rules (Access Control List Rules)

ACL Rules are the primary mechanism for configuring firewall policies in UniFi Network API.

List ACL Rules

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

Query Parameters:

• offset (integer, default: 0)
• limit (integer, default: 25, max: 200)
• filter (string) - Filter expressions

Response: Paginated list of ACL rules

Get ACL Rule Details

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

Response: ACL rule object with:

• type: "IPV4"
• enabled: boolean
• name: string
• description: string
• action: "ALLOW" | "BLOCK"
• index: integer (lower index = higher priority)
• sourceFilter: object (traffic source filter)
• destinationFilter: object (traffic destination filter)
• protocolFilter: array of strings ("TCP", "UDP")
• enforcingDeviceFilter: object (device filter for enforcement)

Create ACL Rule

POST /v1/sites/{siteId}/acl-rules

Request Body:

{
  "type": "IPV4",
  "enabled": true,
  "name": "Rule Name",
  "description": "Rule description",
  "action": "ALLOW|BLOCK",
  "enforcingDeviceFilter": {
    "type": "string"
  },
  "index": 0,
  "sourceFilter": {
    "type": "string"
  },
  "destinationFilter": {
    "type": "string"
  },
  "protocolFilter": ["TCP", "UDP"]
}

Update ACL Rule

PUT /v1/sites/{siteId}/acl-rules/{aclRuleId}

Request Body: Same as Create ACL Rule

Delete ACL Rule

DELETE /v1/sites/{siteId}/acl-rules/{aclRuleId}

---

2. Firewall Zones

Firewall Zones group networks together for firewall policy configuration.

List Firewall Zones

GET /v1/sites/{siteId}/firewall/zones

Query Parameters:

• offset (integer, default: 0)
• limit (integer, default: 25, max: 200)
• filter (string)

Response: List of firewall zones

Get Firewall Zone

GET /v1/sites/{siteId}/firewall/zones/{firewallZoneId}

Response: Firewall zone object with:

• id: UUID
• name: string
• networkIds: array of network UUIDs
• metadata: object

Create Custom Firewall Zone

POST /v1/sites/{siteId}/firewall/zones

Request Body:

{
  "name": "Zone Name",
  "networkIds": ["network-uuid-1", "network-uuid-2"]
}

Update Firewall Zone

PUT /v1/sites/{siteId}/firewall/zones/{firewallZoneId}

Delete Custom Firewall Zone

DELETE /v1/sites/{siteId}/firewall/zones/{firewallZoneId}

---

3. Traffic Matching Lists

Traffic Matching Lists define port and IP address lists used in firewall policies.

List Traffic Matching Lists

GET /v1/sites/{siteId}/traffic-matching-lists

Get Traffic Matching List

GET /v1/sites/{siteId}/traffic-matching-lists/{trafficMatchingListId}

Create Traffic Matching List

POST /v1/sites/{siteId}/traffic-matching-lists

Request Body:

{
  "type": "PORTS",
  "name": "List Name",
  "items": []
}

Update Traffic Matching List

PUT /v1/sites/{siteId}/traffic-matching-lists/{trafficMatchingListId}

Delete Traffic Matching List

DELETE /v1/sites/{siteId}/traffic-matching-lists/{trafficMatchingListId}

---

ACL Rule Configuration Examples

Example 1: Block Inter-VLAN Traffic (Sovereign Tenant Isolation)

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

{
  "type": "IPV4",
  "enabled": true,
  "name": "Block Sovereign Tenant East-West",
  "description": "Deny traffic between sovereign tenant VLANs (200-203)",
  "action": "BLOCK",
  "index": 100,
  "sourceFilter": {
    "type": "NETWORK",
    "networkIds": [
      "network-uuid-vlan-200",
      "network-uuid-vlan-201",
      "network-uuid-vlan-202",
      "network-uuid-vlan-203"
    ]
  },
  "destinationFilter": {
    "type": "NETWORK",
    "networkIds": [
      "network-uuid-vlan-200",
      "network-uuid-vlan-201",
      "network-uuid-vlan-202",
      "network-uuid-vlan-203"
    ]
  },
  "protocolFilter": null
}

Example 2: Allow Management VLAN Access

Allow Management VLAN (11) to access Service VLANs on specific ports:

{
  "type": "IPV4",
  "enabled": true,
  "name": "Allow Management to Service VLANs",
  "description": "Allow VLAN 11 to access service VLANs (SSH, DB, Admin ports)",
  "action": "ALLOW",
  "index": 10,
  "sourceFilter": {
    "type": "NETWORK",
    "networkIds": ["network-uuid-vlan-11"]
  },
  "destinationFilter": {
    "type": "NETWORK",
    "networkIds": [
      "network-uuid-vlan-110",
      "network-uuid-vlan-120",
      "network-uuid-vlan-130"
    ]
  },
  "protocolFilter": ["TCP"],
  "portFilter": {
    "type": "PORTS",
    "ports": [22, 5432, 8080, 443]
  }
}

Example 3: Allow Monitoring Traffic

Allow Service VLANs to send monitoring data to Management VLAN:

{
  "type": "IPV4",
  "enabled": true,
  "name": "Allow Monitoring to Management",
  "description": "Allow service VLANs to send monitoring/logging to VLAN 11",
  "action": "ALLOW",
  "index": 20,
  "sourceFilter": {
    "type": "NETWORK",
    "networkIds": [
      "network-uuid-vlan-110",
      "network-uuid-vlan-120",
      "network-uuid-vlan-130"
    ]
  },
  "destinationFilter": {
    "type": "NETWORK",
    "networkIds": ["network-uuid-vlan-11"]
  },
  "protocolFilter": ["UDP", "TCP"],
  "portFilter": {
    "type": "PORTS",
    "ports": [161, 9090, 9091]
  }
}

---

Important Notes

ACL Rule Priority

• Index Field: Lower index values have higher priority
• Rules are evaluated in order of index (ascending)
• First matching rule applies

Filter Types

ACL Rules support various filter types for source and destination:

• Network Filters: Filter by network/VLAN IDs
• IP Address Filters: Filter by IP addresses or ranges
• Port Filters: Filter by port numbers or ranges
• Protocol Filters: TCP, UDP (or null for all protocols)

Device Enforcement

• enforcingDeviceFilter: Specify which devices enforce the rule
• If null, rule applies to all switches on the site
• Useful for device-specific policies

Network References

To use network IDs in filters:

1. List networks: GET /v1/sites/{siteId}/networks
2. Extract network IDs from the response
3. Use network IDs in ACL rule filters

---

Implementation Strategy

Phase 1: List Current Configuration

1. List existing ACL rules
2. List firewall zones
3. List networks (to get network IDs)
4. Document current state

Phase 2: Create Firewall Rules

1. Sovereign Tenant Isolation:

   • Create BLOCK rules for VLANs 200-203 inter-VLAN traffic

2. Management VLAN Access:

   • Create ALLOW rules for VLAN 11 → Service VLANs
   • Use appropriate port filters

3. Monitoring Access:

   • Create ALLOW rules for Service VLANs → VLAN 11
   • Use monitoring port filters

Phase 3: Verify and Test

1. Verify rules are created correctly
2. Test connectivity between VLANs
3. Adjust priorities (index values) as needed

---

Related Documentation

• UDM_PRO_STATUS.md - Configuration status
• UDM_PRO_API_ENDPOINT_EXPLORATION.md - API endpoint exploration
• UniFi Network API Documentation - Official API documentation

---

Last Updated: 2025-01-20