README.md

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