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