1 lldpd: implementation of IEEE 802.1ab (LLDP)
2 ============================================
4 [![Build Status](https://secure.travis-ci.org/vincentbernat/lldpd.png?branch=master)](http://travis-ci.org/vincentbernat/lldpd)
6 http://vincentbernat.github.com/lldpd/
11 LLDP (Link Layer Discovery Protocol) is an industry standard protocol
12 designed to supplant proprietary Link-Layer protocols such as
13 Extreme's EDP (Extreme Discovery Protocol) and CDP (Cisco Discovery
14 Protocol). The goal of LLDP is to provide an inter-vendor compatible
15 mechanism to deliver Link-Layer notifications to adjacent network
18 lldpd implements both reception and sending. It also implements an
19 SNMP subagent for net-snmp to get local and remote LLDP
20 information. The LLDP-MIB is partially implemented but the most useful
21 tables are here. lldpd also partially implements LLDP-MED.
23 lldpd supports bridge, vlan and bonding.
25 The following OS are supported:
37 For general instructions
38 [see the website](http://vincentbernat.github.io/lldpd/installation.html).
40 To compile lldpd from sources, use the following:
46 lldpd uses privilege separation to increase its security. Two
47 processes, one running as root and doing minimal stuff and the other
48 running as an unprivileged user into a chroot doing most of the stuff,
49 are cooperating. You need to create a user called `_lldpd` in a group
50 `_lldpd` (this can be change with `./configure`). You also need to
51 create an empty directory `/usr/local/var/run/lldpd` (it needs to be
52 owned by root, not `_lldpd`!). If you get fuzzy timestamps from
53 syslog, copy `/etc/locatime` into the chroot.
55 `lldpcli` lets one query information collected through the command
56 line. If you don't want to run it as root, just install it setuid or
59 Installation (Mac OS X)
60 -----------------------
62 The same procedure as above applies for Mac OS X. However, there are
65 1. Use [Homebrew](http://mxcl.github.io/homebrew/):
68 # Or, for the latest version:
69 brew install https://raw.github.com/vincentbernat/lldpd/master/osx/lldpd.rb
71 2. Build an OSX installer package which should work on the same
72 version of OS X (it is important to use a separate build
75 mkdir build && cd build
76 ../configure --prefix=/usr --localstatedir=/var --sysconfdir=/private/etc --with-embedded-libevent
77 make -C osx pkg ARCHS="i386 x86_64"
79 If you want to compile for an older version of Mac OS X, you need
80 to find the right SDK and issues commands like those:
82 SDK=/Developer/SDKs/MacOSX10.6.sdk
83 mkdir build && cd build
84 ../configure --prefix=/usr --localstatedir=/var --sysconfdir=/private/etc --with-embedded-libevent \
85 CFLAGS="-mmacosx-version-min=10.6 -isysroot $SDK" \
86 LDFLAGS="-mmacosx-version-min=10.6 -isysroot $SDK"
87 make -C osx pkg ARCHS="i386 x86_64"
89 If you don't follow the above procedures, you will have to create the
90 user/group `_lldpd`. Have a look at how this is done in
91 `osx/scripts/postinstall`.
93 Installation (Android)
94 ----------------------
96 You need to download [Android NDK][]. Once unpacked, you can generate
97 a toolchain using the following command:
99 ./build/tools/make-standalone-toolchain.sh \
100 --platform=android-9 \
102 --install-dir=../android-toolchain
103 export TOOLCHAIN=$PWD/../android-toolchain
105 Then, you can build `lldpd` with the following commands:
107 mkdir build && cd build
108 export PATH=$PATH:$TOOLCHAIN/bin
110 --host=arm-linux-androideabi \
111 --with-sysroot=$TOOLCHAIN/sysroot
113 [Android NDK]: http://developer.android.com/tools/sdk/ndk/index.html
118 lldpd also implements CDP (Cisco Discovery Protocol), FDP (Foundry
119 Discovery Protocol), SONMP (Nortel Discovery Protocol) and EDP
120 (Extreme Discovery Protocol). However, recent versions of IOS should
121 support LLDP and most Extreme stuff support LLDP. When a EDP, CDP or
122 SONMP frame is received on a given interface, lldpd starts sending
123 EDP, CDP, FDP or SONMP frame on this interface. Informations collected
124 through EDP/CDP/FDP/SONMP are integrated with other informations and
125 can be queried with `lldpcli` or through SNMP.
127 For bonding, you need 2.6.24 (in previous version, PACKET_ORIGDEV
128 affected only non multicast packets). See:
130 * http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commitdiff;h=80feaacb8a6400a9540a961b6743c69a5896b937
131 * http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commitdiff;h=8032b46489e50ef8f3992159abd0349b5b8e476c
133 Otherwise, a packet received on a bond will be affected to all
134 interfaces of the bond.
136 On 2.6.27, we are able to receive packets on real interface for bonded
137 devices. This allows one to get neighbor information on active/backup
138 bonds. Without the 2.6.27, lldpd won't receive any information on
139 inactive slaves. Here are the patchs (thanks to Joe Eykholt):
141 * http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=0d7a3681232f545c6a59f77e60f7667673ef0e93
142 * http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=cc9bd5cebc0825e0fabc0186ab85806a0891104f
143 * http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=f982307f22db96201e41540295f24e8dcc10c78f
145 On FreeBSD, only a recent 9 kernel (9.1 or more recent) will allow to
146 send LLDP frames on enslaved devices. See this bug report for more
149 * http://www.freebsd.org/cgi/query-pr.cgi?pr=138620
151 Some devices (notably Cisco IOS) send frames on tagged with the native
152 VLAN while they should send them untagged. If your network card does
153 not support accelerated VLAN, you will receive those frames as long as
154 the corresponding interface exists (see below). However, if your
155 network card handles VLAN encapsulation/decapsulation (check with
156 `ethtool -k`), you need a recent kernel to be able to receive those
157 frames without listening on all available VLAN. Starting from Linux
158 2.6.27, lldpd is able to capture VLAN frames when VLAN acceleration is
159 supported by the network card. Here is the patch:
161 * http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=bc1d0411b804ad190cdadabac48a10067f17b9e6
163 On some other versions, frames are sent on VLAN 1. If this is not the
164 native VLAN and if your network card support accelerated VLAN, you
165 need to subscribe to this VLAN as well. The Linux kernel does not
166 provide any interface for this. The easiest way is to create the VLAN
169 ip link add link eth0 name eth0.1 type vlan id 1
170 ip link set up dev eth0.1
172 You can check both cases using tcpdump:
174 tcpdump -epni eth0 ether host 01:80:c2:00:00:0e
175 tcpdump -eni eth0 ether host 01:80:c2:00:00:0e
177 If the first command does not display received LLDP packets but the
178 second one does, LLDP packets are likely encapsulated into a VLAN:
180 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
182 In this case, just create VLAN 1 will fix the situation. There are
185 1. Disable VLAN acceleration on the receive side (`ethtool -K eth0
186 rxvlan off`) but this may or may not work. Check if there are
187 similar properties that could apply with `ethtool -k eth0`.
188 2. Put the interface in promiscuous mode with `ip link set
189 promisc on dev eth0`.
191 The last solution can be done directly by `lldpd` (on Linux only) by
192 using the option `configure system interface promiscuous`.
194 On modern networks, the performance impact should be nonexistent.
197 * http://en.wikipedia.org/wiki/Link_Layer_Discovery_Protocol
198 * http://standards.ieee.org/getieee802/download/802.1AB-2005.pdf
199 * http://wiki.wireshark.org/LinkLayerDiscoveryProtocol
204 During development, you may want to execute lldpd at its current
205 location inside of doing `make install`. The correct way to do this is
206 to issue the following command:
208 sudo libtool execute src/daemon/lldpd -L $PWD/src/client/lldpcli -d
210 You can append any further arguments. If lldpd is unable to find
211 `lldpcli` it will start in an unconfigured mode and won't send or
217 To embed lldpd into an existing system, there are two point of entries:
219 1. If your system does not use standard Linux interface, you can
220 support additional interfaces by implementing the appropriate
221 `struct lldpd_ops`. You can look at
222 `src/daemon/interfaces-linux.c` for examples. Also, have a look at
223 `interfaces_update()` which is responsible for discovering and
224 registering interfaces.
226 2. `lldpcli` provides a convenient way to query `lldpd`. It also
227 comes with various outputs, including XML which allows one to
228 parse its output for integration and automation purpose. Another
229 way is to use SNMP support. A third way is to write your own
230 controller using `liblldpctl.so`. Its API is described in
231 `src/lib/lldpctl.h`. The custom binary protocol between
232 `liblldpctl.so` and `lldpd` is not stable. Therefore, the library
233 should always be shipped with `lldpd`. On the other hand, programs
234 using `liblldpctl.so` can rely on the classic ABI rules.
239 You can use `tcpdump` to look after the packets received and send by
240 `lldpd`. To look after LLDPU, use:
242 tcpdump -s0 -vv -pni eth0 ether dst 01:80:c2:00:00:0e
247 lldpd is distributed under the ISC license:
249 > Permission to use, copy, modify, and/or distribute this software for any
250 > purpose with or without fee is hereby granted, provided that the above
251 > copyright notice and this permission notice appear in all copies.
253 > THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
254 > WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
255 > MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
256 > ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
257 > WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
258 > ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
259 > OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
261 Also, `lldpcli` will be linked to GNU Readline (which is GPL licensed)
262 if available. To avoid this, use `--without-readline` as a configure