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