Skip to main content

​
Overview

Xloud Networking distributes work across multiple agents running on compute and network nodes. Monitoring agent health is a core administrative responsibility — a downed agent can silently prevent new port bindings, DHCP assignments, or routing updates. This guide covers how to inspect, manage, and recover agents across your cluster.
Administrator Access Required — This operation requires the admin role. Contact your Xloud administrator if you do not have sufficient permissions.
Prerequisites
  • Admin credentials sourced from admin-openrc.sh
  • openstack CLI installed and configured

​
Inspect Agent Health

Navigate to Network Agents

Log in to the Xloud Dashboard (https://connect.<your-domain>) as an administrator and navigate to Admin → Network → Agents.

Review agent status

Each row represents one agent instance. Review the following columns:
ColumnHealthy ValueAction If Unhealthy
AliveYes (green)Restart the service on the affected host
Admin StateUpEnable via CLI: openstack network agent set --enable
BinaryAgent process nameCheck system service logs on the host
HostFully-qualified hostnameConfirm the host is reachable on the network
Last HeartbeatRecent timestampInvestigate if stale by more than 30 seconds

​
Enable and Disable Agents

Disable an agent before performing maintenance on its host to prevent the scheduler from assigning new work to it. Re-enable after maintenance completes.
Disable agent for maintenance
openstack network agent set <agent-id> --disable
Re-enable agent after maintenance
openstack network agent set <agent-id> --enable
Disabling an L3 or DHCP agent causes affected routers and subnets to lose that agent’s services. Ensure redundant agents are running before disabling any agent. Verify with openstack network agent list that at least one healthy agent of the same type remains.

​
Agent Type Reference

Agent BinaryTypeRuns OnResponsibilities
neutron-dhcp-agentDHCPNetwork nodesIP assignment, DNS, host routes via DHCP
neutron-l3-agentL3Network nodesRouter NAT, floating IPs, VRRP
neutron-openvswitch-agentL2 (SDN)Compute nodesSDN-based L2 switching and port bindings
neutron-linuxbridge-agentLinux bridgeCompute nodesLinux bridge-based L2 switching
neutron-metadata-agentMetadataNetwork nodesInstance metadata proxy
neutron-metering-agentMeteringNetwork nodesTraffic metering for billing

​
Restart an Agent

When an agent shows Alive: False, restart the service on the affected host. Agents running inside Docker containers are managed by XDeploy:
Restart networking agents via XDeploy
xavs-ansible deploy --tags neutron
After restarting, allow up to 30 seconds for the agent to re-register and send a heartbeat. Verify recovery:
Confirm agent is alive
openstack network agent list --long | grep <host-name>
Agent shows Alive: True and a recent heartbeat timestamp.

​
Next Steps

DHCP Configuration

Schedule networks to DHCP agents and configure HA for high availability

L3 Router Configuration

Configure HA and distributed routing across L3 agents

Service Architecture

Understand the distributed agent model and message bus communication

Admin Troubleshooting

Diagnose and resolve agent failures and VXLAN connectivity issues