]>
Commit | Line | Data |
---|---|---|
43c02e7b | 1 | lldpd: implementation of IEEE 802.1ab (LLDP) |
00402c76 | 2 | ============================================ |
43c02e7b | 3 | |
ce05de54 VB |
4 | [![Build Status](https://secure.travis-ci.org/vincentbernat/lldpd.png?branch=master)](http://travis-ci.org/vincentbernat/lldpd) |
5 | ||
bf74bdaf | 6 | http://vincentbernat.github.com/lldpd/ |
f0c42642 | 7 | |
4b292b55 VB |
8 | Features |
9 | -------- | |
10 | ||
43c02e7b VB |
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 | |
16 | devices. | |
17 | ||
18 | lldpd implements both reception and sending. It also implements an | |
19 | SNMP subagent for net-snmp to get local and remote LLDP | |
f7f82e1e | 20 | information. The LLDP-MIB is partially implemented but the most useful |
b193e97e | 21 | tables are here. lldpd also partially implements LLDP-MED. |
43c02e7b | 22 | |
f7f82e1e | 23 | lldpd supports bridge, vlan and bonding. |
c0cdd011 | 24 | |
2b35e2d0 VB |
25 | The following OS are supported: |
26 | ||
27 | * FreeBSD | |
28 | * GNU/Linux | |
ac57139f | 29 | * macOS |
2b35e2d0 VB |
30 | * NetBSD |
31 | * OpenBSD | |
f7f82e1e | 32 | * Solaris |
2b35e2d0 | 33 | |
032c0cf4 VB |
34 | Windows is not supported but you can use |
35 | [WinLLDPService](https://github.com/raspi/WinLLDPService/) as a | |
36 | transmit-only agent. | |
37 | ||
4b292b55 VB |
38 | Installation |
39 | ------------ | |
40 | ||
7edd995b VB |
41 | For general instructions [prefer the |
42 | website](http://vincentbernat.github.io/lldpd/installation.html), | |
43 | including building from released tarballs. | |
ba666663 | 44 | |
7edd995b | 45 | To compile lldpd from Git, use the following commands: |
00402c76 | 46 | |
7edd995b | 47 | ./autogen.sh |
00402c76 VB |
48 | ./configure |
49 | make | |
50 | sudo make install | |
52ac3f37 | 51 | |
13dce469 VB |
52 | lldpd uses privilege separation to increase its security. Two |
53 | processes, one running as root and doing minimal stuff and the other | |
54 | running as an unprivileged user into a chroot doing most of the stuff, | |
00402c76 VB |
55 | are cooperating. You need to create a user called `_lldpd` in a group |
56 | `_lldpd` (this can be change with `./configure`). You also need to | |
ba666663 VB |
57 | create an empty directory `/usr/local/var/run/lldpd` (it needs to be |
58 | owned by root, not `_lldpd`!). If you get fuzzy timestamps from | |
59 | syslog, copy `/etc/locatime` into the chroot. | |
13dce469 | 60 | |
2b35e2d0 | 61 | `lldpcli` lets one query information collected through the command |
33aced7a | 62 | line. If you don't want to run it as root, just install it setuid or |
00402c76 | 63 | setgid `_lldpd`. |
43c02e7b | 64 | |
ac57139f | 65 | Installation (macOS) |
e66b7f34 VB |
66 | ----------------------- |
67 | ||
ac57139f | 68 | The same procedure as above applies for macOS. However, there are |
92f5db08 | 69 | simpler alternatives: |
29e300e5 | 70 | |
37e9556e | 71 | 1. Use [Homebrew](https://brew.sh): |
e66b7f34 | 72 | |
92f5db08 VB |
73 | brew install lldpd |
74 | # Or, for the latest version: | |
75 | brew install https://raw.github.com/vincentbernat/lldpd/master/osx/lldpd.rb | |
b708297c | 76 | |
ac57139f VB |
77 | 2. Build an macOS installer package which should work on the same |
78 | version of macOS: | |
92f5db08 | 79 | |
462d8b6c | 80 | mkdir build && cd build |
87bb9a1b | 81 | ../configure --prefix=/usr/local --localstatedir=/var --sysconfdir=/private/etc --with-embedded-libevent \ |
06987a24 | 82 | --without-snmp |
737afb35 | 83 | make -C osx pkg |
b708297c | 84 | |
ac57139f | 85 | If you want to compile for an older version of macOS, you need |
462d8b6c VB |
86 | to find the right SDK and issues commands like those: |
87 | ||
88 | SDK=/Developer/SDKs/MacOSX10.6.sdk | |
89 | mkdir build && cd build | |
87bb9a1b | 90 | ../configure --prefix=/usr/local --localstatedir=/var --sysconfdir=/private/etc --with-embedded-libevent \ |
06987a24 | 91 | --without-snmp \ |
462d8b6c VB |
92 | CFLAGS="-mmacosx-version-min=10.6 -isysroot $SDK" \ |
93 | LDFLAGS="-mmacosx-version-min=10.6 -isysroot $SDK" | |
737afb35 | 94 | make -C osx pkg |
462d8b6c | 95 | |
6b7d841c VB |
96 | With recent SDK, you don't need to specify an alternate SDK. They |
97 | are organized in a way that should enable compatibility with older | |
98 | versions of OSX: | |
99 | ||
100 | mkdir build && cd build | |
101 | ../configure --prefix=/usr/local --localstatedir=/var --sysconfdir=/private/etc --with-embedded-libevent \ | |
06987a24 | 102 | --without-snmp \ |
6b7d841c VB |
103 | CFLAGS="-mmacosx-version-min=10.9" \ |
104 | LDFLAGS="-mmacosx-version-min=10.9" | |
105 | make -C osx pkg | |
106 | ||
107 | You can check with `otool -l` that you got what you expected in | |
108 | term of supported versions. | |
109 | ||
92f5db08 VB |
110 | If you don't follow the above procedures, you will have to create the |
111 | user/group `_lldpd`. Have a look at how this is done in | |
112 | `osx/scripts/postinstall`. | |
b708297c | 113 | |
8b0ca98e VB |
114 | Installation (Android) |
115 | ---------------------- | |
116 | ||
117 | You need to download [Android NDK][]. Once unpacked, you can generate | |
653838a3 | 118 | a toolchain using the following command (for ARM64): |
8b0ca98e VB |
119 | |
120 | ./build/tools/make-standalone-toolchain.sh \ | |
653838a3 VB |
121 | --platform=android-24 \ |
122 | --arch=arm64 \ | |
8b0ca98e VB |
123 | --install-dir=../android-toolchain |
124 | export TOOLCHAIN=$PWD/../android-toolchain | |
125 | ||
126 | Then, you can build `lldpd` with the following commands: | |
127 | ||
128 | mkdir build && cd build | |
129 | export PATH=$PATH:$TOOLCHAIN/bin | |
130 | ../configure \ | |
653838a3 | 131 | --host=arm64-linux-androideabi \ |
7cae6b6e VB |
132 | --with-sysroot=$TOOLCHAIN/sysroot \ |
133 | --prefix=/system \ | |
f2e7a911 VB |
134 | --sbindir=/system/bin \ |
135 | --runstatedir=/data/data/lldpd \ | |
136 | --with-privsep-user=root \ | |
137 | --with-privsep-group=root | |
7cae6b6e VB |
138 | make |
139 | make install DESTDIR=$PWD/install | |
140 | ||
141 | Then, copy `install/system/bin/*` to `/system/bin` on the target | |
142 | system and `install/system/lib/*.so*` to `/system/lib` on the target | |
f2e7a911 | 143 | system. You may need to create `/data/data/lldpd` as well. |
8b0ca98e VB |
144 | |
145 | [Android NDK]: http://developer.android.com/tools/sdk/ndk/index.html | |
146 | ||
4b292b55 VB |
147 | Usage |
148 | ----- | |
149 | ||
031118c4 VB |
150 | lldpd also implements CDP (Cisco Discovery Protocol), FDP (Foundry |
151 | Discovery Protocol), SONMP (Nortel Discovery Protocol) and EDP | |
152 | (Extreme Discovery Protocol). However, recent versions of IOS should | |
153 | support LLDP and most Extreme stuff support LLDP. When a EDP, CDP or | |
154 | SONMP frame is received on a given interface, lldpd starts sending | |
155 | EDP, CDP, FDP or SONMP frame on this interface. Informations collected | |
156 | through EDP/CDP/FDP/SONMP are integrated with other informations and | |
2b35e2d0 | 157 | can be queried with `lldpcli` or through SNMP. |
43c02e7b | 158 | |
c167357d VB |
159 | More information: |
160 | * http://en.wikipedia.org/wiki/Link_Layer_Discovery_Protocol | |
161 | * http://standards.ieee.org/getieee802/download/802.1AB-2005.pdf | |
162 | * http://wiki.wireshark.org/LinkLayerDiscoveryProtocol | |
163 | ||
164 | Compatibility with older kernels | |
165 | -------------------------------- | |
166 | ||
167 | If you have a kernel older than Linux 2.6.39, you need to compile | |
168 | lldpd with `--enable-oldies` to enable some compatibility functions: | |
169 | otherwise, lldpd will only rely on Netlink to receive bridge, bond and | |
170 | VLAN information. | |
171 | ||
43c02e7b VB |
172 | For bonding, you need 2.6.24 (in previous version, PACKET_ORIGDEV |
173 | affected only non multicast packets). See: | |
00402c76 VB |
174 | |
175 | * http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commitdiff;h=80feaacb8a6400a9540a961b6743c69a5896b937 | |
176 | * http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commitdiff;h=8032b46489e50ef8f3992159abd0349b5b8e476c | |
43c02e7b | 177 | |
c8851c73 | 178 | Otherwise, a packet received on a bond will be affected to all |
c167357d VB |
179 | interfaces of the bond. In this case, lldpd will affect a received |
180 | randomly to one of the interface (so a neighbor may be affected to the | |
181 | wrong interface). | |
43c02e7b | 182 | |
0da01fd6 | 183 | On 2.6.27, we are able to receive packets on real interface for enslaved |
21d89e7d | 184 | devices. This allows one to get neighbor information on active/backup |
43c02e7b VB |
185 | bonds. Without the 2.6.27, lldpd won't receive any information on |
186 | inactive slaves. Here are the patchs (thanks to Joe Eykholt): | |
00402c76 VB |
187 | |
188 | * http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=0d7a3681232f545c6a59f77e60f7667673ef0e93 | |
189 | * http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=cc9bd5cebc0825e0fabc0186ab85806a0891104f | |
190 | * http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=f982307f22db96201e41540295f24e8dcc10c78f | |
43c02e7b | 191 | |
63aebf55 VB |
192 | On FreeBSD, only a recent 9 kernel (9.1 or more recent) will allow to |
193 | send LLDP frames on enslaved devices. See this bug report for more | |
194 | information: | |
195 | ||
196 | * http://www.freebsd.org/cgi/query-pr.cgi?pr=138620 | |
197 | ||
c167357d | 198 | Some devices (notably Cisco IOS) send frames tagged with the native |
50724a52 VB |
199 | VLAN while they should send them untagged. If your network card does |
200 | not support accelerated VLAN, you will receive those frames as long as | |
201 | the corresponding interface exists (see below). However, if your | |
202 | network card handles VLAN encapsulation/decapsulation (check with | |
5f7d1cd5 VB |
203 | `ethtool -k`), you need a recent kernel to be able to receive those |
204 | frames without listening on all available VLAN. Starting from Linux | |
205 | 2.6.27, lldpd is able to capture VLAN frames when VLAN acceleration is | |
206 | supported by the network card. Here is the patch: | |
49697208 | 207 | |
50724a52 VB |
208 | * http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=bc1d0411b804ad190cdadabac48a10067f17b9e6 |
209 | ||
210 | On some other versions, frames are sent on VLAN 1. If this is not the | |
211 | native VLAN and if your network card support accelerated VLAN, you | |
212 | need to subscribe to this VLAN as well. The Linux kernel does not | |
213 | provide any interface for this. The easiest way is to create the VLAN | |
214 | for each port: | |
5f7d1cd5 VB |
215 | |
216 | ip link add link eth0 name eth0.1 type vlan id 1 | |
217 | ip link set up dev eth0.1 | |
218 | ||
219 | You can check both cases using tcpdump: | |
220 | ||
221 | tcpdump -epni eth0 ether host 01:80:c2:00:00:0e | |
222 | tcpdump -eni eth0 ether host 01:80:c2:00:00:0e | |
223 | ||
224 | If the first command does not display received LLDP packets but the | |
225 | second one does, LLDP packets are likely encapsulated into a VLAN: | |
226 | ||
227 | 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 | |
228 | ||
50724a52 VB |
229 | In this case, just create VLAN 1 will fix the situation. There are |
230 | other solutions: | |
231 | ||
232 | 1. Disable VLAN acceleration on the receive side (`ethtool -K eth0 | |
233 | rxvlan off`) but this may or may not work. Check if there are | |
234 | similar properties that could apply with `ethtool -k eth0`. | |
f84199dd VB |
235 | 2. Put the interface in promiscuous mode with `ip link set |
236 | promisc on dev eth0`. | |
50724a52 | 237 | |
f4da5f84 VB |
238 | The last solution can be done directly by `lldpd` (on Linux only) by |
239 | using the option `configure system interface promiscuous`. | |
240 | ||
50724a52 | 241 | On modern networks, the performance impact should be nonexistent. |
5f7d1cd5 | 242 | |
426ee11e VB |
243 | Development |
244 | ----------- | |
245 | ||
246 | During development, you may want to execute lldpd at its current | |
3bd5a878 | 247 | location instead of doing `make install`. The correct way to do this is |
426ee11e VB |
248 | to issue the following command: |
249 | ||
250 | sudo libtool execute src/daemon/lldpd -L $PWD/src/client/lldpcli -d | |
251 | ||
252 | You can append any further arguments. If lldpd is unable to find | |
253 | `lldpcli` it will start in an unconfigured mode and won't send or | |
254 | accept LLDP frames. | |
255 | ||
3ca10086 VB |
256 | You can use [afl](http://lcamtuf.coredump.cx/afl/) to test some |
257 | aspects of lldpd. To test frame decoding, you can do something like | |
258 | that: | |
259 | ||
260 | export AFL_USE_ASAN=1 # only on 32bit arch | |
261 | ./configure CC=afl-gcc | |
262 | make clean check | |
263 | cd tests | |
264 | mkdir inputs | |
265 | mv *.pcap inputs | |
266 | afl-fuzz -i inputs -o outputs ./decode @@ | |
267 | ||
8cd1f2d0 | 268 | There is a general test suite with `make check`. It's also possible to |
e0a84778 VB |
269 | run integration tests. They need [py.test](http://pytest.org/latest/) |
270 | and rely on Linux containers to be executed. | |
8cd1f2d0 | 271 | |
76bae8b9 VB |
272 | To enable code coverage, use: |
273 | ||
274 | ../configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var \ | |
28d521e2 VB |
275 | --enable-sanitizers --enable-gcov --with-snmp \ |
276 | CFLAGS="-O0 -g" | |
76bae8b9 VB |
277 | make |
278 | make check | |
279 | # maybe, run integration tests | |
280 | lcov --base-directory $PWD/src/lib \ | |
281 | --directory src --capture --output-file gcov.info | |
282 | genhtml gcov.info --output-directory coverage | |
283 | ||
4b292b55 VB |
284 | Embedding |
285 | --------- | |
286 | ||
287 | To embed lldpd into an existing system, there are two point of entries: | |
288 | ||
289 | 1. If your system does not use standard Linux interface, you can | |
290 | support additional interfaces by implementing the appropriate | |
e12c2365 VB |
291 | `struct lldpd_ops`. You can look at |
292 | `src/daemon/interfaces-linux.c` for examples. Also, have a look at | |
293 | `interfaces_update()` which is responsible for discovering and | |
294 | registering interfaces. | |
4b292b55 | 295 | |
2b35e2d0 | 296 | 2. `lldpcli` provides a convenient way to query `lldpd`. It also |
4b292b55 VB |
297 | comes with various outputs, including XML which allows one to |
298 | parse its output for integration and automation purpose. Another | |
299 | way is to use SNMP support. A third way is to write your own | |
300 | controller using `liblldpctl.so`. Its API is described in | |
301 | `src/lib/lldpctl.h`. The custom binary protocol between | |
302 | `liblldpctl.so` and `lldpd` is not stable. Therefore, the library | |
303 | should always be shipped with `lldpd`. On the other hand, programs | |
304 | using `liblldpctl.so` can rely on the classic ABI rules. | |
305 | ||
22f1ea46 VB |
306 | Troubleshooting |
307 | --------------- | |
308 | ||
309 | You can use `tcpdump` to look after the packets received and send by | |
310 | `lldpd`. To look after LLDPU, use: | |
311 | ||
312 | tcpdump -s0 -vv -pni eth0 ether dst 01:80:c2:00:00:0e | |
313 | ||
db4383dd VB |
314 | Intel X710 cards may handle LLDP themselves, intercepting any incoming |
315 | packets. If you don't see anything through `tcpdump`, check if you | |
316 | have such a card (with `lspci`) and stop the embedded LLDP daemon: | |
317 | ||
318 | for f in /sys/kernel/debug/i40e/*/command; do | |
319 | echo lldp stop > $f | |
320 | done | |
321 | ||
4b292b55 VB |
322 | License |
323 | ------- | |
324 | ||
c882a2cf | 325 | lldpd is distributed under the ISC license: |
00402c76 | 326 | |
51434125 | 327 | > Permission to use, copy, modify, and/or distribute this software for any |
00402c76 VB |
328 | > purpose with or without fee is hereby granted, provided that the above |
329 | > copyright notice and this permission notice appear in all copies. | |
330 | > | |
331 | > THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES | |
332 | > WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF | |
333 | > MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR | |
334 | > ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | |
335 | > WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | |
336 | > ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF | |
337 | > OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | |
35f6f4fb VB |
338 | |
339 | Also, `lldpcli` will be linked to GNU Readline (which is GPL licensed) | |
340 | if available. To avoid this, use `--without-readline` as a configure | |
341 | option. |