osx: update version in HomeBrew formula

[thirdparty/lldpd.git] / README.md

diff --git a/README.md b/README.md
index 3c24649a32b2b58c928624b79128ca493c9e4868..f61b6505b1481af2d48918864482977f63e8b35a 100644 (file)
--- a/README.md
+++ b/README.md
@@ -3,7 +3,7 @@ lldpd: implementation of IEEE 802.1ab (LLDP)
 
 [![Build Status](https://secure.travis-ci.org/vincentbernat/lldpd.png?branch=master)](http://travis-ci.org/vincentbernat/lldpd)
 
 
 [![Build Status](https://secure.travis-ci.org/vincentbernat/lldpd.png?branch=master)](http://travis-ci.org/vincentbernat/lldpd)
 

-  https://github.com/vincentbernat/lldpd/wiki
+  http://vincentbernat.github.com/lldpd/

 
 Features
 --------
 
 Features
 --------


@@ -17,49 +17,133 @@ devices.
 
 lldpd implements both reception and sending. It also implements an
 SNMP subagent for net-snmp to get local and remote LLDP
 
 lldpd implements both reception and sending. It also implements an
 SNMP subagent for net-snmp to get local and remote LLDP

-information. The LLDP MIB is partially implemented but the most useful
+information. The LLDP-MIB is partially implemented but the most useful

 tables are here. lldpd also partially implements LLDP-MED.
 
 tables are here. lldpd also partially implements LLDP-MED.
 

-lldpd supports bridge, vlan and bonding. bonding need to be done on
-real physical devices, not on bridges, vlans, etc. However, vlans can
-be mapped on the bonding device. You can bridge vlan but not add vlans
-on bridges. More complex setups may give false results.
+lldpd supports bridge, vlan and bonding.
+
+The following OS are supported:
+
+ * FreeBSD
+ * GNU/Linux
+ * macOS
+ * NetBSD
+ * OpenBSD
+ * Solaris
+
+Windows is not supported but you can use
+[WinLLDPService](https://github.com/raspi/WinLLDPService/) as a
+transmit-only agent.

 
 Installation
 ------------
 
 
 Installation
 ------------
 

-To compile lldpd, use the following:
+For general instructions [prefer the
+website](http://vincentbernat.github.io/lldpd/installation.html),
+including building from released tarballs.

 
 

+To compile lldpd from Git, use the following commands:
+
+    ./autogen.sh

     ./configure
     make
     sudo make install
 
     ./configure
     make
     sudo make install
 

-You need libevent that you can grab from http://libevent.org or
-install from your package system (libevent-dev for Debian/Ubuntu and
-libevent-devel for Redhat/Fedora/CentOS/SuSE).
-
-If your system does not have libevent, ./configure will use the
-shipped copy and compile it statically.
-
-If it complains about a missing agent/struct.h, your installation of
-Net-SNMP is incomplete. The easiest way to fix this is to provide an
-empty struct.h:
-
-    touch src/struct.h
-

 lldpd uses privilege separation to increase its security. Two
 processes, one running as root and doing minimal stuff and the other
 running as an unprivileged user into a chroot doing most of the stuff,
 are cooperating. You need to create a user called `_lldpd` in a group
 `_lldpd` (this can be change with `./configure`). You also need to
 lldpd uses privilege separation to increase its security. Two
 processes, one running as root and doing minimal stuff and the other
 running as an unprivileged user into a chroot doing most of the stuff,
 are cooperating. You need to create a user called `_lldpd` in a group
 `_lldpd` (this can be change with `./configure`). You also need to

-create an empty directory `/var/run/lldpd` (it needs to be owned by
-root, not `_lldpd`!). If you get fuzzy timestamps from syslog, copy
-`/etc/locatime` into the chroot.
+create an empty directory `/usr/local/var/run/lldpd` (it needs to be
+owned by root, not `_lldpd`!). If you get fuzzy timestamps from
+syslog, copy `/etc/locatime` into the chroot.

 
 

-`lldpctl` lets one query information collected through the command
+`lldpcli` lets one query information collected through the command

 line. If you don't want to run it as root, just install it setuid or
 setgid `_lldpd`.
 
 line. If you don't want to run it as root, just install it setuid or
 setgid `_lldpd`.
 

+Installation (macOS)
+-----------------------
+
+The same procedure as above applies for macOS. However, there are
+simpler alternatives:
+
+ 1. Use [Homebrew](https://brew.sh):
+
+        brew install lldpd
+        # Or, for the latest version:
+        brew install https://raw.github.com/vincentbernat/lldpd/master/osx/lldpd.rb
+
+ 2. Build an macOS installer package which should work on the same
+    version of macOS:
+ 
+        mkdir build && cd build
+        ../configure --prefix=/usr/local --localstatedir=/var --sysconfdir=/private/etc --with-embedded-libevent \
+            --without-snmp
+        make -C osx pkg
+
+    If you want to compile for an older version of macOS, you need
+    to find the right SDK and issues commands like those:
+
+        SDK=/Developer/SDKs/MacOSX10.6.sdk
+        mkdir build && cd build
+        ../configure --prefix=/usr/local --localstatedir=/var --sysconfdir=/private/etc --with-embedded-libevent \
+           --without-snmp \
+           CFLAGS="-mmacosx-version-min=10.6 -isysroot $SDK" \
+           LDFLAGS="-mmacosx-version-min=10.6 -isysroot $SDK"
+        make -C osx pkg
+
+    With recent SDK, you don't need to specify an alternate SDK. They
+    are organized in a way that should enable compatibility with older
+    versions of OSX:
+
+        mkdir build && cd build
+        ../configure --prefix=/usr/local --localstatedir=/var --sysconfdir=/private/etc --with-embedded-libevent \
+           --without-snmp \
+           CFLAGS="-mmacosx-version-min=10.9" \
+           LDFLAGS="-mmacosx-version-min=10.9"
+        make -C osx pkg
+
+    You can check with `otool -l` that you got what you expected in
+    term of supported versions.
+
+If you don't follow the above procedures, you will have to create the
+user/group `_lldpd`. Have a look at how this is done in
+`osx/scripts/postinstall`.
+
+Installation (Android)
+----------------------
+
+You need to download [Android NDK][]. Once unpacked, you can generate
+a toolchain using the following command:
+
+    ./build/tools/make-standalone-toolchain.sh \
+        --platform=android-9 \
+        --arch=arm \
+        --install-dir=../android-toolchain
+    export TOOLCHAIN=$PWD/../android-toolchain
+
+Then, you can build `lldpd` with the following commands:
+
+    mkdir build && cd build
+    export PATH=$PATH:$TOOLCHAIN/bin
+    ../configure \
+        --host=arm-linux-androideabi \
+        --with-sysroot=$TOOLCHAIN/sysroot \
+        --prefix=/system \
+        --sbindir=/system/bin \
+        --runstatedir=/data/data/lldpd \
+        --with-privsep-user=root \
+        --with-privsep-group=root
+    make
+    make install DESTDIR=$PWD/install
+
+Then, copy `install/system/bin/*` to `/system/bin` on the target
+system and `install/system/lib/*.so*` to `/system/lib` on the target
+system. You may need to create `/data/data/lldpd` as well.
+
+[Android NDK]: http://developer.android.com/tools/sdk/ndk/index.html
+

 Usage
 -----
 
 Usage
 -----
 


@@ -70,7 +154,20 @@ support LLDP and most Extreme stuff support LLDP. When a EDP, CDP or
 SONMP frame is received on a given interface, lldpd starts sending
 EDP, CDP, FDP or SONMP frame on this interface. Informations collected
 through EDP/CDP/FDP/SONMP are integrated with other informations and
 SONMP frame is received on a given interface, lldpd starts sending
 EDP, CDP, FDP or SONMP frame on this interface. Informations collected
 through EDP/CDP/FDP/SONMP are integrated with other informations and

-can be queried with `lldpctl` or through SNMP.
+can be queried with `lldpcli` or through SNMP.
+
+More information:
+ * http://en.wikipedia.org/wiki/Link_Layer_Discovery_Protocol
+ * http://standards.ieee.org/getieee802/download/802.1AB-2005.pdf
+ * http://wiki.wireshark.org/LinkLayerDiscoveryProtocol
+
+Compatibility with older kernels
+--------------------------------
+
+If you have a kernel older than Linux 2.6.39, you need to compile
+lldpd with `--enable-oldies` to enable some compatibility functions:
+otherwise, lldpd will only rely on Netlink to receive bridge, bond and
+VLAN information.

 
 For bonding, you need 2.6.24 (in previous version, PACKET_ORIGDEV
 affected only non multicast packets). See:
 
 For bonding, you need 2.6.24 (in previous version, PACKET_ORIGDEV
 affected only non multicast packets). See:


@@ -79,9 +176,11 @@ affected only non multicast packets). See:
  * http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commitdiff;h=8032b46489e50ef8f3992159abd0349b5b8e476c
 
 Otherwise, a packet received on a bond will be affected to all
  * http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commitdiff;h=8032b46489e50ef8f3992159abd0349b5b8e476c
 
 Otherwise, a packet received on a bond will be affected to all

-interfaces of the bond.
+interfaces of the bond. In this case, lldpd will affect a received
+randomly to one of the interface (so a neighbor may be affected to the
+wrong interface).

 
 

-On 2.6.27, we are able to receive packets on real interface for bonded
+On 2.6.27, we are able to receive packets on real interface for enslaved

 devices. This allows one to get neighbor information on active/backup
 bonds. Without the 2.6.27, lldpd won't receive any information on
 inactive slaves. Here are the patchs (thanks to Joe Eykholt):
 devices. This allows one to get neighbor information on active/backup
 bonds. Without the 2.6.27, lldpd won't receive any information on
 inactive slaves. Here are the patchs (thanks to Joe Eykholt):


@@ -96,20 +195,91 @@ information:
 
  * http://www.freebsd.org/cgi/query-pr.cgi?pr=138620
 
 
  * http://www.freebsd.org/cgi/query-pr.cgi?pr=138620
 

-Some devices (notably Cisco IOS) send frames on the native VLAN while
-they should send them untagged. If your network card does not support
-accelerated VLAN, you will receive those frames as well. However, if
-your network card handles VLAN encapsulation/decapsulation, you need a
-recent kernel to be able to receive those frames without listening on
-all available VLAN. Starting from Linux 2.6.27, lldpd is able to
-capture VLAN frames when VLAN acceleration is supported by the network
-card. Here is the patch:
- http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=bc1d0411b804ad190cdadabac48a10067f17b9e6
+Some devices (notably Cisco IOS) send frames tagged with the native
+VLAN while they should send them untagged. If your network card does
+not support accelerated VLAN, you will receive those frames as long as
+the corresponding interface exists (see below). However, if your
+network card handles VLAN encapsulation/decapsulation (check with
+`ethtool -k`), you need a recent kernel to be able to receive those
+frames without listening on all available VLAN. Starting from Linux
+2.6.27, lldpd is able to capture VLAN frames when VLAN acceleration is
+supported by the network card. Here is the patch:

 
 

-More information:
- * http://en.wikipedia.org/wiki/Link_Layer_Discovery_Protocol
- * http://standards.ieee.org/getieee802/download/802.1AB-2005.pdf
- * http://wiki.wireshark.org/LinkLayerDiscoveryProtocol
+ * http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=bc1d0411b804ad190cdadabac48a10067f17b9e6
+
+On some other versions, frames are sent on VLAN 1. If this is not the
+native VLAN and if your network card support accelerated VLAN, you
+need to subscribe to this VLAN as well. The Linux kernel does not
+provide any interface for this. The easiest way is to create the VLAN
+for each port:
+
+    ip link add link eth0 name eth0.1 type vlan id 1
+    ip link set up dev eth0.1
+
+You can check both cases using tcpdump:
+
+    tcpdump -epni eth0 ether host 01:80:c2:00:00:0e
+    tcpdump -eni eth0 ether host 01:80:c2:00:00:0e
+
+If the first command does not display received LLDP packets but the
+second one does, LLDP packets are likely encapsulated into a VLAN:
+
+    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
+
+In this case, just create VLAN 1 will fix the situation. There are
+other solutions:
+
+ 1. Disable VLAN acceleration on the receive side (`ethtool -K eth0
+    rxvlan off`) but this may or may not work. Check if there are
+    similar properties that could apply with `ethtool -k eth0`.
+ 2. Put the interface in promiscuous mode with `ip link set
+    promisc on dev eth0`.
+
+The last solution can be done directly by `lldpd` (on Linux only) by
+using the option `configure system interface promiscuous`.
+
+On modern networks, the performance impact should be nonexistent.
+
+Development
+-----------
+
+During development, you may want to execute lldpd at its current
+location instead of doing `make install`. The correct way to do this is
+to issue the following command:
+
+    sudo libtool execute src/daemon/lldpd -L $PWD/src/client/lldpcli -d
+
+You can append any further arguments. If lldpd is unable to find
+`lldpcli` it will start in an unconfigured mode and won't send or
+accept LLDP frames.
+
+You can use [afl](http://lcamtuf.coredump.cx/afl/) to test some
+aspects of lldpd. To test frame decoding, you can do something like
+that:
+
+    export AFL_USE_ASAN=1 # only on 32bit arch
+    ./configure CC=afl-gcc
+    make clean check
+    cd tests
+    mkdir inputs
+    mv *.pcap inputs
+    afl-fuzz -i inputs -o outputs ./decode @@
+
+There is a general test suite with `make check`. It's also possible to
+run integration tests. They need [py.test](http://pytest.org/latest/)
+and rely on Linux containers to be executed.
+
+To enable code coverage, use:
+
+    ../configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var \
+                 --enable-sanitizers --enable-gcov --with-snmp \
+                 CFLAGS="-O0 -g"
+    make
+    make check
+    # maybe, run integration tests
+    lcov --base-directory $PWD/src/lib \
+         --directory src --capture --output-file gcov.info
+    genhtml gcov.info --output-directory coverage

 
 Embedding
 ---------
 
 Embedding
 ---------


@@ -123,7 +293,7 @@ To embed lldpd into an existing system, there are two point of entries:
     `interfaces_update()` which is responsible for discovering and
     registering interfaces.
 
     `interfaces_update()` which is responsible for discovering and
     registering interfaces.
 

- 2. `lldpctl` provides a convenient way to query `lldpd`. It also
+ 2. `lldpcli` provides a convenient way to query `lldpd`. It also

     comes with various outputs, including XML which allows one to
     parse its output for integration and automation purpose. Another
     way is to use SNMP support. A third way is to write your own
     comes with various outputs, including XML which allows one to
     parse its output for integration and automation purpose. Another
     way is to use SNMP support. A third way is to write your own


@@ -133,6 +303,22 @@ To embed lldpd into an existing system, there are two point of entries:
     should always be shipped with `lldpd`. On the other hand, programs
     using `liblldpctl.so` can rely on the classic ABI rules.
 
     should always be shipped with `lldpd`. On the other hand, programs
     using `liblldpctl.so` can rely on the classic ABI rules.
 

+Troubleshooting
+---------------
+
+You can use `tcpdump` to look after the packets received and send by
+`lldpd`. To look after LLDPU, use:
+
+    tcpdump -s0 -vv -pni eth0 ether dst 01:80:c2:00:00:0e
+
+Intel X710 cards may handle LLDP themselves, intercepting any incoming
+packets. If you don't see anything through `tcpdump`, check if you
+have such a card (with `lspci`) and stop the embedded LLDP daemon:
+
+    for f in /sys/kernel/debug/i40e/*/command; do
+        echo lldp stop > $f
+    done
+

 License
 -------
 
 License
 -------