lldptool

@amitmund September 11, 2026

Linux `lldptool` — Complete Learning Notes & Output Guide

lldptool is the configuration and interrogation utility for the Linux Link Layer Discovery Protocol agent daemon (lldpad). Operating at Data Link Layer 2 (IEEE 802.1AB), it queries physical network neighbors (switches, routers, upstream servers) and manages Type-Length-Value (TLV) frames, including Data Center Bridging Exchange (DCBX) parameters for RoCE and SAN fabrics.

1. What is `lldptool`?

lldptool provides Layer 2 visibility without needing IP configuration, default gateways, or routing tables. It communicates with the background daemon lldpad over a local UNIX domain socket (/var/run/lldpad/).

It answers essential infrastructure and cabling questions:

Which physical switch chassis, rack unit, and switch port is this server's interface cabled to?
What is the native VLAN (PVID) configured on the upstream switch port?
What are the remote switch's system capabilities (Bridge, Router, WLAN, Station)?
Are Priority-based Flow Control (PFC) and Enhanced Transmission Selection (ETS) being negotiated correctly over DCBX for lossless Ethernet (RoCEv2 / FCoE)?
What is the management IP address of the adjacent top-of-rack (ToR) switch?

2. Architecture: `lldpad` and Layer 2 Discovery

LLDP packets are transmitted periodically to a well-known multicast MAC address (01:80:C2:00:00:0E, 01:80:C2:00:00:03, or 01:80:C2:00:00:00). These frames are intercepted by the physical link partner and are not forwarded across Layer 3 hops.

+-------------------------------------------------------------+
|                        USER SPACE                           |
|   lldptool (CLI) <---> /var/run/lldpad/ <---> lldpad (Daemon)
+-------------------------------------------------------------+
                               |
                               v (PF_PACKET raw sockets)
+-------------------------------------------------------------+
|                     LINUX KERNEL / NIC                      |
|   eth0 / eno1 (Physical Port)                               |
+-------------------------------------------------------------+
                               |
                               | IEEE 802.1AB LLDP Frames (L2 Multicast)
                               v
+-------------------------------------------------------------+
|                 ADJACENT TOP-OF-RACK SWITCH                 |
|   Switch: "tor-sw01.rack4" | Port: "Ethernet1/12" (Trunk)   |
+-------------------------------------------------------------+

3. Installation & Daemon Setup

lldptool requires the lldpad package and its background service.

Debian / Ubuntu

sudo apt update
sudo apt install lldpad

RHEL / Rocky / AlmaLinux / CentOS

sudo dnf install lldpad

Arch Linux

sudo pacman -S open-lldp

Enable and Start the Daemon

lldptool cannot function without lldpad actively running:

sudo systemctl enable --now lldpad
systemctl status lldpad

4. Basic Syntax & Core Operation Modes

lldptool <command> [options] [arguments]

Primary Command Flags

Flag / Option	Purpose	Practical Example
`-t`	Interrogate/query TLV data.	`lldptool -t -i eth0`
`-n`	Target neighbor information (received remote data).	`lldptool -t -n -i eth0`
`-i <iface>`	Target a specific network interface.	`lldptool -t -n -i eth0`
`-V <tlvid>`	Filter output to a specific TLV type (e.g., `sysName`, `portDesc`).	`lldptool -t -n -i eth0 -V sysName`
`-L` / `-l`	Query (`-l`) or set (`-L`) global/local configuration parameters.	`lldptool -l`
`set-lldp`	Configure the administrative reception/transmission state of an interface.	`lldptool set-lldp -i eth0 adminStatus=rx_tx`
`set-tlv`	Configure which TLVs the local agent broadcasts to neighbors.	`lldptool -T -i eth0 -V sysName enableTx=yes`

5. Enabling LLDP on an Interface

By default, lldpad starts in a disabled administrative state on all interfaces. You must enable it before neighbors can be detected or advertised.

# 1. Enable both receiving (RX) and transmitting (TX) on eth0
sudo lldptool set-lldp -i eth0 adminStatus=rx_tx

# 2. Enable transmission of optional basic TLVs to the switch
sudo lldptool -T -i eth0 -V sysName enableTx=yes
sudo lldptool -T -i eth0 -V sysDesc enableTx=yes
sudo lldptool -T -i eth0 -V portDesc enableTx=yes
sudo lldptool -T -i eth0 -V sysCap enableTx=yes
sudo lldptool -T -i eth0 -V mngAddr enableTx=yes

# 3. Verify administrative status
lldptool get-lldp -i eth0 adminStatus
# Output: adminStatus=rx_tx

6. Anatomy of Neighbor Query Output (`lldptool -t -n -i <iface>`)

Once the upstream switch broadcasts an LLDP frame (typically every 30 seconds), query the neighbor database:

lldptool -t -n -i eth0

Raw Output Example

Chassis ID TLV
    MAC: 00:1c:73:a1:b2:00
Port ID TLV
    Ifname: Ethernet1/24
Time to Live TLV
    120
System Name TLV
    leaf01-tor.dc2.internal
System Description TLV
    Arista Networks EOS version 4.28.1F running on Arista DCS-7050SX3-48YC8
System Capabilities TLV
    System capabilities: Bridge, Router
    Enabled capabilities: Bridge, Router
Management Address TLV
    IPv4: 10.200.1.51
    Ifindex: 1001
Port Description TLV
    Server-Rack-04-Node-A_eth0
Port VLAN ID TLV
    100
IEEE 802.3 MAC/PHY Configuration Status TLV
    Auto-negotiation: supported and enabled
    PMD auto-negotiation advertised capability: 10GBASE-CR, 25GBASE-CR
    Operational MAU type: 25GBASE-CR-S

7. Breakdown of Every Output Heading & TLV Field

+-----------------------+-----------------------------+---------------------------------------+
| TLV Name              | Example Value               | Technical Meaning                     |
+-----------------------+-----------------------------+---------------------------------------+
| Chassis ID TLV        | MAC: 00:1c:73:a1:b2:00      | Unique hardware ID of remote switch   |
| Port ID TLV           | Ifname: Ethernet1/24        | Physical remote switch port identifier|
| Time to Live TLV      | 120                         | Validity lifetime of neighbor record  |
+-----------------------+-----------------------------+---------------------------------------+

7.1 `Chassis ID TLV`

Format: Subtype followed by identifier (e.g., MAC: 00:1c:73:a1:b2:00 or Chassis component: Rack4-Chassis1).
Meaning: The global identifier representing the remote chassis. In data centers, this is commonly the base MAC address of the upstream switch backplane.

7.2 `Port ID TLV`

Format: Subtype followed by identifier (e.g., Ifname: Ethernet1/24, Locally assigned: 521, or MAC: ...).
Meaning: Identifies the exact physical interface on the remote device into which the server's cable is plugged.
Troubleshooting Significance: Crucial for physical server identification and cabling verification.

7.3 `Time to Live TLV`

Format: Integer in seconds (e.g., 120).
Meaning: How long the local receiver should hold this neighbor's state before evicting it if no subsequent LLDP advertisement frames are received.

7.4 `System Name TLV`

Format: String (e.g., leaf01-tor.dc2.internal).
Meaning: The configured DNS/FQDN hostname of the adjacent switch.

7.5 `System Description TLV`

Format: Free-form string.
Meaning: Switch operating system details, vendor hardware architecture, and firmware release (e.g., Cisco NX-OS, Arista EOS, Cumulus Linux).

7.6 `System Capabilities TLV`

Format:
System capabilities: Hardware features supported by the remote device.
Enabled capabilities: Features currently active in software.
Common Capability Flags:
Bridge: Standard Layer 2 Ethernet switch.
Router: Active Layer 3 routing engine.
WLAN: Wireless access point.
Station: End-host or server.

7.7 `Management Address TLV`

Format: IPv4: <address> or IPv6: <address>, accompanied by Ifindex.
Meaning: Out-of-band or in-band IP address assigned to the switch for SSH/SNMP management. Allows an operator to immediately determine what IP to log into to configure the switch port.

7.8 `Port VLAN ID TLV` (PVID / Native VLAN)

Format: Integer (e.g., 100).
Meaning: The default untagged Native VLAN ID assigned to this physical port on the switch.
Troubleshooting Significance: If the server sends untagged frames, this tells you which VLAN the switch assigns those packets to.

8. Data Center Bridging (DCB) & RoCE Tuning (`lldptool -T -x`)

In high-performance networking, High-Performance Computing (HPC), and storage clusters (NVMe-oF, Ceph, RoCEv2), lldptool configures and inspects Data Center Bridging Exchange (DCBX).

DCBX exchanges configuration parameters between the switch and NIC to maintain a lossless Ethernet fabric.

# Query DCBX configuration state on eth0
lldptool -t -i eth0 -V dcbx

# Inspect Priority-based Flow Control (PFC) negotiation
lldptool -t -i eth0 -V pfc

Raw PFC Output Example

Priority Flow Control TLV
    Willing: yes
    MACsec Bypass Capable: no
    PFC enabled priorities: 3
    Number of PFC priorities supported: 8

Key DCBX Metrics Explained

Willing (yes/no): Indicates whether the local NIC accepts configuration parameters pushed down by the upstream switch (yes = auto-configure from switch; no = enforce local host settings).
PFC enabled priorities (e.g., 3): The 802.1p Quality of Service (QoS) priority class assigned to lossless traffic. Priority 3 is the data center standard for RoCEv2 traffic.
Enhanced Transmission Selection (ETS): Allocates guaranteed bandwidth percentages to specific traffic classes to ensure storage traffic cannot starve management or application traffic.

9. Real-World Troubleshooting Scenarios

Scenario A: Cabling Verification (Tracing the Upstream Switch Port)

You rack a new server, plug cables into eth0 and eth1, and need to document switch and port mappings without walking into the data center or tracing physical wires:

sudo lldptool set-lldp -i eth0 adminStatus=rx_tx
sudo lldptool set-lldp -i eth1 adminStatus=rx_tx
sleep 30
lldptool -t -n -i eth0 -V sysName
lldptool -t -n -i eth0 -V portID

Output:

System Name TLV
    tor-sw-rack04-a.infra.net
Port ID TLV
    Ifname: Ethernet1/3

Result: Server port eth0 is confirmed cabled directly to tor-sw-rack04-a, physical port Ethernet1/3.

Scenario B: Diagnosing Silent Packet Drops Due to PVID / VLAN Mismatch

A host cannot obtain an IP address via DHCP or reach its gateway on eth0, although ethtool reports Link detected: yes.

Inspect the switch port's native VLAN via LLDP:

lldptool -t -n -i eth0 -V PortVLANID

Output:

Port VLAN ID TLV
    200

Diagnosis: The upstream switch port is set to Native VLAN 200, but the server's network configuration expects untagged traffic on VLAN 100. Frames are being placed into the wrong broadcast domain by the switch.

Scenario C: Neighbor Output is Empty Despite Active Link

Running lldptool -t -n -i eth0 returns no output at all:

lldptool -t -n -i eth0
# (Blank or returns error connecting to lldpad)

Troubleshooting Checklist:

Check lldpad service: Confirm daemon is running:

sudo systemctl status lldpad

Verify adminStatus: Confirm RX is active:

lldptool get-lldp -i eth0 adminStatus

If disabled, run: sudo lldptool set-lldp -i eth0 adminStatus=rx_tx. 3. Switch Configuration: Many enterprise switches (Cisco, Arista) disable LLDP transmission globally by default in favor of CDP. The network engineer must run:

switch(config)# lldp run
switch(config-if)# lldp transmit
switch(config-if)# lldp receive

10. `lldptool` vs. `lldpcli` (Open-LLDP vs. lldpd)

Linux provides two distinct, mutually exclusive LLDP software implementations:

Feature / Dimension	`lldptool` (`open-lldp`)	`lldpcli` (`lldpd`)
Backing Daemon	`lldpad`	`lldpd`
Primary Focus	DCBX, FCoE, RoCE, Enterprise SANs	Simple network discovery, CDP/EDP decoding
Alternative Protocol Support	Strict IEEE 802.1AB LLDP	Supports LLDP, CDP (Cisco), EDP, SONMP, FDP
JSON/XML Output	No (ASCII only)	Native (`lldpcli -f json show neighbors`)
Kernel DCB Netlink	Full integration with kernel DCB	Basic support
Ease of Ad-Hoc Use	Verbose setup (`adminStatus=rx_tx` required)	Automatic discovery out-of-the-box

11. Important Interview Questions & Answers

Q: What is the difference between LLDP and Cisco's CDP (Cisco Discovery Protocol)?

Answer: LLDP (IEEE 802.1AB) is an open, vendor-neutral standard supported by all major networking and server hardware vendors. CDP is a Cisco-proprietary Layer 2 discovery protocol. While CDP is largely restricted to Cisco gear, modern multi-protocol daemons like lldpd can speak both, whereas open-lldp (lldptool) focuses strictly on standard IEEE 802.1AB and DCBX extensions.

Q: Why does `lldptool` require setting `adminStatus=rx_tx` before it displays any data?

Answer: By design, open-lldp starts with interface discovery turned off to avoid unintentionally broadcasting system information or altering power-saving states. Setting adminStatus=rx_tx explicitly instructs the driver and daemon to bind raw Layer 2 PF_PACKET sockets to the interface, listen for multicast destination addresses (01:80:C2:00:00:0E), and allow the transmission of local host identity frames.

Q: What role does `lldptool` play in configuring Lossless RoCE (RDMA over Converged Ethernet)?

Answer: RDMA over Converged Ethernet version 2 (RoCEv2) cannot tolerate dropped packets under congestion. It relies on 802.1Qbb Priority-based Flow Control (PFC) to send pause frames on dedicated priority queues. lldptool uses DCBX (Data Center Bridging Exchange) TLVs over LLDP to dynamically synchronize and validate PFC priorities, buffer allocations, and ETS bandwidth reservations between host NIC firmware and upstream switch ASICs.

Linux lldptool — Complete Learning Notes & Output Guide

1. What is lldptool?

2. Architecture: lldpad and Layer 2 Discovery