Skip to content
This repository

implementation of IEEE 802.1ab (LLDP)

Octocat-spinner-32 .travis travis: put installation and test instructions into shell scripts March 03, 2014
Octocat-spinner-32 debian version: prepare new release April 13, 2014
Octocat-spinner-32 include include: don't ship `linux/socket.h` December 31, 2013
Octocat-spinner-32 libevent @ e826f19 libevent: switch to patches-2.0 branch to get the appropriate automak… June 09, 2013
Octocat-spinner-32 m4 configure: make some flags conditional April 12, 2014
Octocat-spinner-32 osx osx: new release April 13, 2014
Octocat-spinner-32 redhat version: prepare new release April 13, 2014
Octocat-spinner-32 src lldpcli: document new "configure system hostname" directive April 13, 2014
Octocat-spinner-32 tests snmp: link with Net-SNMP later April 06, 2014
Octocat-spinner-32 .gitignore gitignore: add GNU global files November 17, 2013
Octocat-spinner-32 .gitmodules libevent: use GitHub git tree June 09, 2013
Octocat-spinner-32 .travis.yml travis: put installation and test instructions into shell scripts March 03, 2014
Octocat-spinner-32 CONTRIBUTE.md doc: add a CONTRIBUTE document July 03, 2013
Octocat-spinner-32 Makefile.am systemd: install service file using `systemdsystemunit_DATA` August 15, 2013
Octocat-spinner-32 NEWS NEWS: add several items to the changelog April 13, 2014
Octocat-spinner-32 README.md README: add build instructions for Android December 31, 2013
Octocat-spinner-32 autogen.sh build: on OSX, use glibtoolize by default March 03, 2014
Octocat-spinner-32 configure.ac configure: make some flags conditional April 12, 2014
Octocat-spinner-32 doxygen.am Separate daemon and client code. Provide a client library. August 28, 2012
Octocat-spinner-32 doxygen.cfg doc: fix doxygen warnings and don't parse include/linux January 05, 2013
Octocat-spinner-32 get-version build: use the same way as libbsd for version and changelog February 20, 2013
README.md

lldpd: implementation of IEEE 802.1ab (LLDP)

Build Status

http://vincentbernat.github.com/lldpd/

Features

LLDP (Link Layer Discovery Protocol) is an industry standard protocol designed to supplant proprietary Link-Layer protocols such as Extreme's EDP (Extreme Discovery Protocol) and CDP (Cisco Discovery Protocol). The goal of LLDP is to provide an inter-vendor compatible mechanism to deliver Link-Layer notifications to adjacent network devices.

lldpd implements both reception and sending. It also implements an SNMP subagent for net-snmp to get local and remote LLDP information. The LLDP MIB is partially implemented but the most useful tables are here. lldpd also partially implements LLDP-MED.

lldpd supports bridge, vlan and bonding. bonding need to be done on real physical devices, not on bridges, vlans, etc. However, vlans can be mapped on the bonding device. You can bridge vlan but not add vlans on bridges. More complex setups may give false results.

The following OS are supported:

  • FreeBSD
  • GNU/Linux
  • NetBSD
  • OpenBSD
  • Mac OS X

Installation

To compile lldpd, use the following:

./configure
make
sudo make install

You need libevent that you can grab from http://libevent.org or install from your package system (libevent-dev for Debian/Ubuntu and libevent-devel for Redhat/Fedora/CentOS/SuSE).

If your system does not have libevent, ./configure will use the shipped copy and compile it statically.

If it complains about a missing agent/struct.h, your installation of Net-SNMP is incomplete. The easiest way to fix this is to provide an empty struct.h:

touch src/struct.h

lldpd uses privilege separation to increase its security. Two processes, one running as root and doing minimal stuff and the other running as an unprivileged user into a chroot doing most of the stuff, are cooperating. You need to create a user called _lldpd in a group _lldpd (this can be change with ./configure). You also need to create an empty directory /var/run/lldpd (it needs to be owned by root, not _lldpd!). If you get fuzzy timestamps from syslog, copy /etc/locatime into the chroot.

lldpcli lets one query information collected through the command line. If you don't want to run it as root, just install it setuid or setgid _lldpd.

Installation (Mac OS X)

The same procedure as above applies for Mac OS X. However, there are simpler alternatives:

  1. Use Homebrew:

    brew install lldpd
    # Or, for the latest version:
    brew install https://raw.github.com/vincentbernat/lldpd/master/osx/lldpd.rb
    
  2. Build an OSX installer package which should work on the same version of OS X (it is important to use a separate build directory):

    mkdir build && cd build
    ../configure --prefix=/usr --sysconfdir=/private/etc --with-embedded-libevent
    make -C osx pkg ARCHS="i386 x86_64"
    

    If you want to compile for an older version of Mac OS X, you need to find the right SDK and issues commands like those:

    SDK=/Developer/SDKs/MacOSX10.6.sdk
    mkdir build && cd build
    ../configure --prefix=/usr --sysconfdir=/private/etc --with-embedded-libevent \
       CFLAGS="-mmacosx-version-min=10.6 -isysroot $SDK" \
       LDFLAGS="-mmacosx-version-min=10.6 -isysroot $SDK"
    make -C osx pkg ARCHS="i386 x86_64"
    

If you don't follow the above procedures, you will have to create the user/group _lldpd. Have a look at how this is done in osx/scripts/postinstall.

Installation (Android)

You need to download Android NDK. Once unpacked, you can generate a toolchain using the following command:

./build/tools/make-standalone-toolchain.sh \
    --platform=android-9 \
    --arch=arm \
    --install-dir=../android-toolchain
export TOOLCHAIN=$PWD/../android-toolchain

Then, you can build lldpd with the following commands:

mkdir build && cd build
export PATH=$PATH:$TOOLCHAIN/bin
../configure \
    --host=arm-linux-androideabi \
    --with-sysroot=$TOOLCHAIN/sysroot

Usage

lldpd also implements CDP (Cisco Discovery Protocol), FDP (Foundry Discovery Protocol), SONMP (Nortel Discovery Protocol) and EDP (Extreme Discovery Protocol). However, recent versions of IOS should support LLDP and most Extreme stuff support LLDP. When a EDP, CDP or SONMP frame is received on a given interface, lldpd starts sending EDP, CDP, FDP or SONMP frame on this interface. Informations collected through EDP/CDP/FDP/SONMP are integrated with other informations and can be queried with lldpcli or through SNMP.

For bonding, you need 2.6.24 (in previous version, PACKET_ORIGDEV affected only non multicast packets). See:

Otherwise, a packet received on a bond will be affected to all interfaces of the bond.

On 2.6.27, we are able to receive packets on real interface for bonded devices. This allows one to get neighbor information on active/backup bonds. Without the 2.6.27, lldpd won't receive any information on inactive slaves. Here are the patchs (thanks to Joe Eykholt):

On FreeBSD, only a recent 9 kernel (9.1 or more recent) will allow to send LLDP frames on enslaved devices. See this bug report for more information:

Some devices (notably Cisco IOS) send frames on the native VLAN while they should send them untagged. If your network card does not support accelerated VLAN, you will receive those frames as well. However, if your network card handles VLAN encapsulation/decapsulation (check with ethtool -k), you need a recent kernel to be able to receive those frames without listening on all available VLAN. Starting from Linux 2.6.27, lldpd is able to capture VLAN frames when VLAN acceleration is supported by the network card. Here is the patch: http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=bc1d0411b804ad190cdadabac48a10067f17b9e6

On some versions, frames are sent on VLAN 1. If your network card support accelerated VLAN, you need to subscribe to this VLAN as well. The Linux kernel does not provide any interface for this. The easiest way is to create the VLAN for each port:

ip link add link eth0 name eth0.1 type vlan id 1
ip link set up dev eth0.1

You can check both cases using tcpdump:

tcpdump -epni eth0 ether host 01:80:c2:00:00:0e
tcpdump -eni eth0 ether host 01:80:c2:00:00:0e

If the first command does not display received LLDP packets but the second one does, LLDP packets are likely encapsulated into a VLAN:

10:54:06.431154 f0:29:29:1d:7c:01 > 01:80:c2:00:00:0e, ethertype 802.1Q (0x8100), length 363: vlan 1, p 7, ethertype LLDP, LLDP, name SW-APP-D07.VTY, length 345

In this case, just create VLAN 1 will fix the situation.

More information:

Development

During development, you may want to execute lldpd at its current location inside of doing make install. The correct way to do this is to issue the following command:

sudo libtool execute src/daemon/lldpd -L $PWD/src/client/lldpcli -d

You can append any further arguments. If lldpd is unable to find lldpcli it will start in an unconfigured mode and won't send or accept LLDP frames.

Embedding

To embed lldpd into an existing system, there are two point of entries:

  1. If your system does not use standard Linux interface, you can support additional interfaces by implementing the appropriate struct lldpd_ops. You can look at src/daemon/interfaces-linux.c for examples. Also, have a look at interfaces_update() which is responsible for discovering and registering interfaces.

  2. lldpcli provides a convenient way to query lldpd. It also comes with various outputs, including XML which allows one to parse its output for integration and automation purpose. Another way is to use SNMP support. A third way is to write your own controller using liblldpctl.so. Its API is described in src/lib/lldpctl.h. The custom binary protocol between liblldpctl.so and lldpd is not stable. Therefore, the library should always be shipped with lldpd. On the other hand, programs using liblldpctl.so can rely on the classic ABI rules.

Troubleshooting

You can use tcpdump to look after the packets received and send by lldpd. To look after LLDPU, use:

tcpdump -s0 -vv -pni eth0 ether dst 01:80:c2:00:00:0e

License

lldpd is distributed under the ISC license:

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Also, lldpcli will be linked to GNU Readline (which is GPL licensed) if available. To avoid this, use --without-readline as a configure option.

Something went wrong with that request. Please try again.