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   https://github.com/vincentbernat/lldpd/wiki
   7
   8 LLDP (Link Layer Discovery Protocol) is an industry standard protocol
   9 designed to supplant proprietary Link-Layer protocols such as
  10 Extreme's EDP (Extreme Discovery Protocol) and CDP (Cisco Discovery
  11 Protocol). The goal of LLDP is to provide an inter-vendor compatible
  12 mechanism to deliver Link-Layer notifications to adjacent network
  13 devices.
  14
  15 lldpd implements both reception and sending. It also implements an
  16 SNMP subagent for net-snmp to get local and remote LLDP
  17 information. The LLDP MIB is partially implemented but the most useful
  18 tables are here. lldpd also partially implements LLDP-MED.
  19
  20 lldpd supports bridge, vlan and bonding. bonding need to be done on
  21 real physical devices, not on bridges, vlans, etc. However, vlans can
  22 be mapped on the bonding device. You can bridge vlan but not add vlans
  23 on bridges. More complex setups may give false results.
  24
  25 To compile lldpd, use the following:
  26
  27     ./configure
  28     make
  29     sudo make install
  30
  31 You need libevent that you can grab from http://libevent.org or
  32 install from your package system (libevent-dev for Debian/Ubuntu and
  33 libevent-devel for Redhat/Fedora/CentOS/SuSE).
  34
  35 If your system does not have libevent, here is a quick howto to
  36 download it and compile it statically into lldpd:
  37
  38     # Grab and compile libevent
  39     wget https://github.com/downloads/libevent/libevent/libevent-2.0.16-stable.tar.gz
  40     tar zxvf libevent-2.0.16-stable.tar.gz
  41     cd libevent-2.0.16-stable
  42     ./configure --prefix=$PWD/usr/local --enable-static --disable-shared
  43     make
  44     make install
  45
  46     # Compile lldpd with static linking
  47     cd ..
  48     ./configure --with-libevent=libevent-2.0.16-stable/usr/local/lib/libevent.la
  49     make
  50     sudo make install
  51
  52 If it complains about a missing agent/struct.h, your installation of
  53 Net-SNMP is incomplete. The easiest way to fix this is to provide an
  54 empty struct.h:
  55
  56     touch src/struct.h
  57
  58 If you are missing some headers or if some headers are incorrect
  59 (if_vlan.h and if_bonding.h on RHEL 2.1 for example), you can copy
  60 some more current version (for example from Debian Lenny or from
  61 Fedora) in some directory like "extra-headers/":
  62
  63  - `./extra-headers/linux/if_vlan.h`
  64  - `./extra-headers/linux/if_bonding.h`
  65
  66 Then, configure like this:
  67
  68     ./configure CFLAGS="-Wall -I${PWD}/extra-headers"
  69
  70 This has been tested with RHEL 2.1.
  71
  72 lldpd uses privilege separation to increase its security. Two
  73 processes, one running as root and doing minimal stuff and the other
  74 running as an unprivileged user into a chroot doing most of the stuff,
  75 are cooperating. You need to create a user called `_lldpd` in a group
  76 `_lldpd` (this can be change with `./configure`). You also need to
  77 create an empty directory `/var/run/lldpd` (it needs to be owned by
  78 root, not `_lldpd`!). If you get fuzzy timestamps from syslog, copy
  79 `/etc/locatime` into the chroot.
  80
  81 `lldpctl` lets one query information collected through the command
  82 line. If you don't want to run it as root, just install it setuid or
  83 setgid `_lldpd`.
  84
  85 lldpd also implements CDP (Cisco Discovery Protocol), FDP (Foundry
  86 Discovery Protocol), SONMP (Nortel Discovery Protocol) and EDP
  87 (Extreme Discovery Protocol). However, recent versions of IOS should
  88 support LLDP and most Extreme stuff support LLDP. When a EDP, CDP or
  89 SONMP frame is received on a given interface, lldpd starts sending
  90 EDP, CDP, FDP or SONMP frame on this interface. Informations collected
  91 through EDP/CDP/FDP/SONMP are integrated with other informations and
  92 can be queried with `lldpctl` or through SNMP.
  93
  94 For bonding, you need 2.6.24 (in previous version, PACKET_ORIGDEV
  95 affected only non multicast packets). See:
  96
  97  * http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commitdiff;h=80feaacb8a6400a9540a961b6743c69a5896b937
  98  * http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commitdiff;h=8032b46489e50ef8f3992159abd0349b5b8e476c
  99
 100 Otherwise, a packet received on a bond will be affected to all
 101 interfaces of the bond.
 102
 103 On 2.6.27, we are able to receive packets on real interface for bonded
 104 devices. This allows one to get neighbor information on active/backup
 105 bonds. Without the 2.6.27, lldpd won't receive any information on
 106 inactive slaves. Here are the patchs (thanks to Joe Eykholt):
 107
 108  * http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=0d7a3681232f545c6a59f77e60f7667673ef0e93
 109  * http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=cc9bd5cebc0825e0fabc0186ab85806a0891104f
 110  * http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=f982307f22db96201e41540295f24e8dcc10c78f
 111
 112 Some devices (notably Cisco IOS) send frames on the native VLAN while
 113 they should send them untagged. If your network card does not support
 114 accelerated VLAN, you will receive those frames as well. However, if
 115 your network card handles VLAN encapsulation/decapsulation, you need a
 116 recent kernel to be able to receive those frames without listening on
 117 all available VLAN. Starting from Linux 2.6.27, lldpd is able to
 118 capture VLAN frames when VLAN acceleration is supported by the network
 119 card. Here is the patch:
 120  http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=bc1d0411b804ad190cdadabac48a10067f17b9e6
 121
 122 More information:
 123  * http://en.wikipedia.org/wiki/Link_Layer_Discovery_Protocol
 124  * http://standards.ieee.org/getieee802/download/802.1AB-2005.pdf
 125  * http://wiki.wireshark.org/LinkLayerDiscoveryProtocol
 126
 127 lldpd is distributed under the following license:
 128
 129  > Permission to use, copy, modify, and/or distribute this software for any
 130  > purpose with or without fee is hereby granted, provided that the above
 131  > copyright notice and this permission notice appear in all copies.
 132  >
 133  > THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 134  > WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 135  > MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 136  > ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 137  > WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 138  > ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 139  > OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.