The Documentation Debt
Static documentation is a lie. In any infrastructure growing faster than a few racks a year, the paperwork is usually the first thing to rot. I’ve lost count of the hours I spent squinting at blurry Visio diagrams or hunting through Excel sheets, only to realize a server was moved to a different switch port three months ago without anyone updating the log. It’s a losing battle where the physical cabling is the only real source of truth.
Six months ago, I killed the manual mapping process entirely. I replaced it with an automated discovery system built on lldpd. This setup has handled hundreds of nodes in production without a single crash. By using Layer 2 discovery protocols like LLDP (Link Layer Discovery Protocol) and CDP (Cisco Discovery Protocol), my Linux servers now report their exact location. They identify their upstream switch, the specific port they occupy, and the management IP of the fabric they live on.
Quick Start: See Your Neighbors in 5 Minutes
The fastest way to gain visibility is the lldpd daemon. While other tools exist, I prefer lldpd because it’s incredibly lightweight—consuming less than 10MB of RAM—and speaks almost every protocol, including LLDP, CDP, FDP, and SONMP.
1. Installation
For Debian or Ubuntu systems:
sudo apt update
sudo apt install lldpd -yFor RHEL, CentOS, or AlmaLinux:
sudo dnf install epel-release -y
sudo dnf install lldpd -y2. Enable and Start
sudo systemctl enable --now lldpd3. Inspect the Neighbors
Give the daemon about 30 seconds to exchange its first set of packets. Then, run:
lldpcli show neighborsIf you are plugged into a managed switch with LLDP or CDP active, you will see a detailed breakdown like this:
Interface: eth0, via: LLDP, RID: 1, Time: 0 day, 00:01:24
Chassis:
ChassisID: mac 00:25:90:7a:bc:de
SysName: Core-Switch-01
SysDescr: Cisco Nexus Operating System (NX-OS) Software
MgmtIP: 10.10.50.1
Capability: Bridge, Router
Port:
PortID: ifname Ethernet1/12
PortDescr: Server-Rack-A1-Node-05
VLAN: 100How Topology Discovery Actually Works
Layer 2 discovery protocols don’t care about your IP address. They operate by broadcasting small frames at regular intervals, typically every 30 seconds. These frames carry Type-Length-Value (TLV) units—essentially small data packets containing the host’s identity. Because this happens at the Data Link layer, discovery works even if your server has no IP assigned to the interface.
LLDP vs. CDP: Why Use Both?
LLDP is the industry standard (IEEE 802.1AB). Every modern vendor like Arista, Juniper, and HP supports it. CDP, however, is Cisco’s proprietary legacy. The reason lldpd is my go-to choice is its bilingual nature. It captures CDP frames from older Cisco gear while simultaneously talking LLDP to the rest of the rack. This eliminates the “vendor lock-in” headache during hardware refreshes.
The Power of lldpcli
The lldpcli tool acts as the management interface for the background daemon. While I usually automate it, the interactive mode is a lifesaver for troubleshooting. For example, if you suspect a bad cable or a misconfigured port channel, run:
lldpcli watchThis provides a live feed of discovery events. If a network engineer changes a VLAN or moves a cable, you’ll see the update hit your screen in real-time.
Automating the Inventory
Mapping one server is a neat trick. Mapping 500 servers is a transformation. To make this data useful at scale, we need to move away from human-readable text and into structured data.
JSON Export
Native JSON support is built directly into lldpcli. This makes it the perfect foundation for automation scripts:
lldpcli -f json show neighborsA Simple Python Integration
I use a small Python wrapper to feed this data into NetBox or a central monitoring database. Here is a basic script to parse your neighbors:
import subprocess
import json
def get_network_neighbors():
try:
# Run the command and capture the JSON output
result = subprocess.run(['lldpcli', '-f', 'json', 'show', 'neighbors'],
capture_output=True, text=True)
data = json.loads(result.stdout)
# Navigate the lldpd JSON structure
interfaces = data.get('lldp', {}).get('interface', {})
for iface_name, details in interfaces.items():
neighbor = details.get('chassis', [{}])[0]
port = details.get('port', [{}])[0]
print(f"Interface {iface_name} is connected to {neighbor.get('name')} on port {port.get('id')}")
except Exception as e:
print(f"Error parsing LLDP data: {e}")
if __name__ == "__main__":
get_network_neighbors()Lessons from the Data Center Floor
1. Don’t Leak Your Map
LLDP is a security risk if it’s exposed to the public internet. It broadcasts your internal naming schemes and management IPs to anyone on the other end of the wire. Always restrict lldpd to internal interfaces. You can do this easily in the configuration:
# Only listen on management and backend NICs
sudo lldpcli configure system interface pattern eth1,eth22. The Virtualization Trap
LLDP packets usually die at the Linux bridge. If you’re running KVM or Docker, the physical switch won’t see the VM, and the VM won’t see the switch. My recommendation? Run lldpd on the hypervisor host itself rather than trying to pass frames through to guest virtual machines.
3. Dealing with “Silent” Switches
If lldpcli show neighbors comes up empty, the switch is likely the culprit. Unmanaged “dumb” switches don’t support these protocols. On Cisco hardware, you might need to explicitly turn it on using lldp run in the global configuration mode.
4. Connect to Your NMS
By enabling the optional SNMP subagent, tools like LibreNMS or Zabbix can pull LLDP data automatically. This creates a self-healing map of your entire network. When a cable moves, the map updates itself within minutes.
Switching to lldpd changed how my team handles outages. We stopped asking “Which port is this?” and started fixing the problem immediately. It turns a 20-minute manual tracing job into a 2-second command. In a production outage, that time is the difference between a minor blip and a major incident.
