Skip to main content

​
Overview

This guide covers infrastructure-level networking issues that require administrator access to diagnose and resolve — agent failures, VXLAN tunnel connectivity, HA router failover, and MTU configuration across the physical underlay.
Administrator Access Required — This operation requires the admin role. Contact your Polystack administrator if you do not have sufficient permissions.
Prerequisites
  • Admin credentials sourced from openrc.sh
  • SSH access to compute and network nodes
  • the deployment console access for agent restarts

​
Diagnostic Quick Reference

Overview agent health across the cluster
List agents by host
Show all routers with HA state

​
Common Issues

Cause: The agent process has crashed, the host is unreachable, or the message bus is not delivering heartbeats.Resolution:
  1. Identify the affected host:
    List agents with heartbeat timestamps
  2. SSH to the affected host and check the agent service:
    Check L2 agent (Linux bridge)
    Check agent container logs
  3. Restart the agent via the deployment console:
    Redeploy networking agents
After restarting, allow up to 30 seconds for the agent to re-register and send a heartbeat. Verify with openstack network agent list --long.
Cause: MTU mismatch, firewall blocking UDP 4789, or misconfigured tunnel endpoint IPs.Resolution:
  1. Verify UDP 4789 (VXLAN) is reachable between compute nodes:
    Test VXLAN port reachability
  2. Confirm tunnel endpoint IPs:
    Show L2 agent configuration including tunnel IP
    The Configuration field shows tunnel_types and local_ip.
  3. Verify the physical interface MTU accommodates VXLAN overhead:
    Check physical interface MTU
    For VXLAN, the physical MTU must be at least 1550 to carry 1500-byte tenant frames with 50-byte encapsulation overhead.
Cause: Tenant network MTU exceeds the physical network capacity after VXLAN encapsulation overhead.Resolution:
  1. Set the correct MTU on the affected tenant network:
    Update network MTU
  2. The DHCP agent automatically pushes the updated MTU to new instances via DHCP option 26. Existing instances need a manual update or DHCP renewal:
    Set MTU on Linux guest
MTU recommendations: VXLAN networks = 1450, VLAN networks = 1500, jumbo-frame VLAN = up to 9000 (requires switch support end-to-end).
Cause: VRRP failover completed but the new master has not programmed floating IP NAT rules, or the failover did not complete.Resolution:
  1. Check the HA state across L3 agents:
    Show router HA status
  2. List L3 agents for the router — confirm one is active:
    List L3 agents for the router
  3. If stuck, trigger rescheduling by toggling admin state:
    Reschedule the HA router
  4. Check L3 agent logs on network nodes for VRRP negotiation errors:
    View L3 agent logs
A long VRRP keepalive timeout (default ~3 seconds, dead interval ~10 seconds) can cause a 10–30 second outage before the standby takes over. Tune the VRRP timers in the deployment console if faster failover is required.
Cause: Physical network mapping misconfiguration or the L2 agent on the compute node does not have the bridge mapped.Resolution:
  1. Verify the bridge mapping on the affected compute node:
    Check bridge mapping in L2 agent config
  2. Confirm the bridge exists on the host:
    Check bridge on compute node
  3. If the bridge is missing, redeploy the networking configuration:
    Redeploy networking

​
Log Locations

​
Next Steps

Network Agent Management

Manage agent enable/disable state and monitor health

L3 Router Configuration

Configure HA and DVR to prevent the issues described in this guide

Provider Networks

Verify provider network configuration if port bindings are failing

User Troubleshooting

Tenant-facing connectivity and floating IP troubleshooting