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 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. bonding need to be done on
  24 real physical devices, not on bridges, vlans, etc. However, vlans can
  25 be mapped on the bonding device. You can bridge vlan but not add vlans
  26 on bridges. More complex setups may give false results.
  27
  28 Installation
  29 ------------
  30
  31 To compile lldpd, use the following:
  32
  33     ./configure
  34     make
  35     sudo make install
  36
  37 You need libevent that you can grab from http://libevent.org or
  38 install from your package system (libevent-dev for Debian/Ubuntu and
  39 libevent-devel for Redhat/Fedora/CentOS/SuSE).
  40
  41 If your system does not have libevent, ./configure will use the
  42 shipped copy and compile it statically.
  43
  44 If it complains about a missing agent/struct.h, your installation of
  45 Net-SNMP is incomplete. The easiest way to fix this is to provide an
  46 empty struct.h:
  47
  48     touch src/struct.h
  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 `/var/run/lldpd` (it needs to be owned by
  56 root, not `_lldpd`!). If you get fuzzy timestamps from syslog, copy
  57 `/etc/locatime` into the chroot.
  58
  59 `lldpctl` 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 Usage
  64 -----
  65
  66 lldpd also implements CDP (Cisco Discovery Protocol), FDP (Foundry
  67 Discovery Protocol), SONMP (Nortel Discovery Protocol) and EDP
  68 (Extreme Discovery Protocol). However, recent versions of IOS should
  69 support LLDP and most Extreme stuff support LLDP. When a EDP, CDP or
  70 SONMP frame is received on a given interface, lldpd starts sending
  71 EDP, CDP, FDP or SONMP frame on this interface. Informations collected
  72 through EDP/CDP/FDP/SONMP are integrated with other informations and
  73 can be queried with `lldpctl` or through SNMP.
  74
  75 For bonding, you need 2.6.24 (in previous version, PACKET_ORIGDEV
  76 affected only non multicast packets). See:
  77
  78  * http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commitdiff;h=80feaacb8a6400a9540a961b6743c69a5896b937
  79  * http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commitdiff;h=8032b46489e50ef8f3992159abd0349b5b8e476c
  80
  81 Otherwise, a packet received on a bond will be affected to all
  82 interfaces of the bond.
  83
  84 On 2.6.27, we are able to receive packets on real interface for bonded
  85 devices. This allows one to get neighbor information on active/backup
  86 bonds. Without the 2.6.27, lldpd won't receive any information on
  87 inactive slaves. Here are the patchs (thanks to Joe Eykholt):
  88
  89  * http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=0d7a3681232f545c6a59f77e60f7667673ef0e93
  90  * http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=cc9bd5cebc0825e0fabc0186ab85806a0891104f
  91  * http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=f982307f22db96201e41540295f24e8dcc10c78f
  92
  93 On FreeBSD, only a recent 9 kernel (9.1 or more recent) will allow to
  94 send LLDP frames on enslaved devices. See this bug report for more
  95 information:
  96
  97  * http://www.freebsd.org/cgi/query-pr.cgi?pr=138620
  98
  99 Some devices (notably Cisco IOS) send frames on the native VLAN while
 100 they should send them untagged. If your network card does not support
 101 accelerated VLAN, you will receive those frames as well. However, if
 102 your network card handles VLAN encapsulation/decapsulation, you need a
 103 recent kernel to be able to receive those frames without listening on
 104 all available VLAN. Starting from Linux 2.6.27, lldpd is able to
 105 capture VLAN frames when VLAN acceleration is supported by the network
 106 card. Here is the patch:
 107  http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=bc1d0411b804ad190cdadabac48a10067f17b9e6
 108
 109 More information:
 110  * http://en.wikipedia.org/wiki/Link_Layer_Discovery_Protocol
 111  * http://standards.ieee.org/getieee802/download/802.1AB-2005.pdf
 112  * http://wiki.wireshark.org/LinkLayerDiscoveryProtocol
 113
 114 Embedding
 115 ---------
 116
 117 To embed lldpd into an existing system, there are two point of entries:
 118
 119  1. If your system does not use standard Linux interface, you can
 120     support additional interfaces by implementing the appropriate
 121     `struct lldpd_ops`. You can look at
 122     `src/daemon/interfaces-linux.c` for examples. Also, have a look at
 123     `interfaces_update()` which is responsible for discovering and
 124     registering interfaces.
 125
 126  2. `lldpctl` provides a convenient way to query `lldpd`. It also
 127     comes with various outputs, including XML which allows one to
 128     parse its output for integration and automation purpose. Another
 129     way is to use SNMP support. A third way is to write your own
 130     controller using `liblldpctl.so`. Its API is described in
 131     `src/lib/lldpctl.h`. The custom binary protocol between
 132     `liblldpctl.so` and `lldpd` is not stable. Therefore, the library
 133     should always be shipped with `lldpd`. On the other hand, programs
 134     using `liblldpctl.so` can rely on the classic ABI rules.
 135
 136 License
 137 -------
 138
 139 lldpd is distributed under the ISC license:
 140
 141  > Permission to use, copy, modify, and/or distribute this software for any
 142  > purpose with or without fee is hereby granted, provided that the above
 143  > copyright notice and this permission notice appear in all copies.
 144  >
 145  > THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 146  > WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 147  > MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 148  > ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 149  > WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 150  > ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 151  > OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.