README.md

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