build: run cross-platforms test on ubuntu-latest

[thirdparty/lldpd.git] / src / daemon / lldpd.8.in

.\" Copyright (c) 2006 Pierre-Yves Ritschard <pyr@openbsd.org>
.\" Copyright (c) 2008 Vincent Bernat <bernat@luffy.cx>
.\"
.\" Permission to use, copy, modify, and/or distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: August 21 2008 $
.Dt LLDPD 8
.Os
.Sh NAME
.Nm lldpd
.Nd LLDP daemon
.Sh SYNOPSIS
.Nm
.Op Fl dxcseiklrv
.Op Fl D Ar debug
.Op Fl p Ar pidfile
.Op Fl S Ar description
.Op Fl P Ar platform
.Op Fl X Ar socket
.Op Fl m Ar management
.Op Fl u Ar file
.Op Fl I Ar interfaces
.Op Fl C Ar interfaces
.Op Fl M Ar class
.Op Fl H Ar hide
.Op Fl L Ar lldpcli
.Op Fl O Ar configfile
.Sh DESCRIPTION
.Nm
is a daemon able to receive and send
.Em LLDP
frames. The Link Layer Discovery Protocol is a vendor-neutral Layer 2
protocol that allows a network device to advertise its identity and
capabilities on the local network.
.Pp
.Nm
also implements an SNMP subagent using AgentX protocol to interface to
a regular SNMP agent like Net-SNMP. To enable this subagent, you need
something like that in your
.Xr snmpd.conf 5 :
.Bd -literal -offset indent
master agentx
.Ed
.Pp
This daemon implements both reception and sending. It will collect
various information to send LLDP frames to all Ethernet interfaces,
including management address, speed and VLAN names.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl d
Do not daemonize.
If this option is specified,
.Nm
will run in the foreground. When specified one more time,
.Nm
will not log to syslog but only to stderr. Then, this option can be
specified many times to increase verbosity. When specified four times,
debug logs will be enabled. They can be filtered with
.Fl D
flag.
.It Fl D Ar debug
This option allows the user to filter out debugging information by
specifying allowed tokens. This option can be repeated several times
to allow several tokens. This option must be combined with the
.Fl d
flag to have some effect. Only debugging logs can be filtered. Here is
a list of allowed tokens with their description:
.Bl -tag -width "XXXXXXXXXX" -offset "XXXX" -compact
.It Sy main
Main daemon.
.It Sy interfaces
Discovery of local interfaces.
.It Sy lldp
LLDP PDU encoding/decoding.
.It Sy edp
EDP PDU encoding/decoding.
.It Sy cdp
CDP/FDP PDU encoding/decoding.
.It Sy sonmp
SONMP PDU encoding/decoding.
.It Sy event
Events management.
.It Sy libevent
Events management but for logs generated by libevent.
.It Sy privsep
Privilege separation.
.It Sy localchassis
Retrieval of information related to the local chassis.
.It Sy rpc
Client communication.
.It Sy control
Management of the Unix control socket.
.It Sy snmp
SNMP subagent.
.It Sy libsnmp
SNMP subagent but for logs generated by NetSNMP.
.It Sy decode
Generic PDU decoding.
.It Sy marshal
Low-level serialization mechanisms.
.It Sy alloc
Low-level allocation mechanisms.
.It Sy send
Sending PDU to some interface.
.It Sy receive
Receiving PDU from some interface.
.It Sy loop
Main loop.
.It Sy smartfilter
Smart filtering of different protocols on the same port.
.It Sy netlink
Netlink subsystem.
.El
.It Fl p Ar pidfile
Use the provided PID file to record
.Nm
PID instead of @LLDPD_PID_FILE@.
.It Fl k
Disable advertising of kernel release, version and machine. Kernel name
(ie: Linux) will still be shared, and Inventory software version will be set
to 'Unknown'.
.It Fl S Ar description
Override system description with the provided description. The default
description is the kernel name, the node name, the kernel version, the
build date and the architecture (except if you use the
.Fl k
flag described above).
.It Fl P Ar platform
Override the CDP platform name with the provided value. The default
description is the kernel name (Linux).
.It Fl x
Enable SNMP subagent.
With this option,
.Nm
will enable an SNMP subagent using AgentX protocol. This allows you to
get information about the local system and remote systems through SNMP.
.It Fl X Ar socket
Enable SNMP subagent using the specified socket.
.Nm
will enable an SNMP subagent using AgentX protocol for the given
socket. This option implies the previous one. The default socket is
usually
.Em /var/agentx/master .
You can specify a socket like
.Em tcp:127.0.0.1:705
for example. Since the process that will open this socket is enclosed
in a chroot, you need to specify an IP address (not a hostname) when
using a TCP or UDP socket.
.It Fl c
Enable the support of CDP protocol to deal with Cisco routers that do
not speak LLDP. If repeated, CDPv1 packets will be sent even when
there is no CDP peer detected. If repeated once again, CDPv2 packets
will be sent even when there is no CDP peer detected. If repeated once
again (i.e.
.Fl cccc ) ,
CDPv1 will be disabled and CDPv2 will be enabled. If repeated once
again (i.e.
.Fl ccccc ) ,
CDPv1 will be disabled and CDPv2 will be forced.
.It Fl f
Enable the support of FDP protocol to deal with Foundry routers that do
not speak LLDP. If repeated, FDP packets will be sent even when there
is no FDP peer detected.
.It Fl s
Enable the support of SONMP protocol to deal with Nortel routers and
switches that do not speak LLDP. If repeated, SONMP packets will be
sent even when there is no SONMP peer detected.
.It Fl e
Enable the support of EDP protocol to deal with Extreme routers and
switches that do not speak LLDP. If repeated, EDP packets will be sent
even when there is no EDP peer detected.
.It Fl l
Force to send LLDP packets even when there is no LLDP peer detected
but there is a peer speaking another protocol detected. By default,
LLDP packets are sent when there is a peer speaking LLDP detected or
when there is no peer at all. If repeated, LLDP is disabled.
.It Fl r
Receive-only mode. With this switch,
.Nm
will not send any frame. It will only listen to neighbors.
.It Fl m Ar management
Specify the management addresses of this system. As for interfaces
(described below), this option can use wildcards and inversions.
Without this option, the first IPv4 and the first IPv6 are used. If an
exact IP address is provided, it is used as a management address
without any check. If only negative patterns are provided, only one
IPv4 and one IPv6 addresses are chosen. Otherwise, many of them can be
selected. If you want to remove IPv6 addresses, you can use
.Em !*:* .
If an interface name is matched, the first IPv4 address and the first
IPv6 address associated to this interface will be chosen.
.It Fl u Ar file
Specify the Unix-domain socket used for communication with
.Xr lldpctl 8 .
.It Fl I Ar interfaces
Specify which interface to listen upon and send LLDPDU from. Without this
option,
.Nm
will use all available physical interfaces. This option can use
wildcards. Several interfaces can be specified separated by commas.
It is also possible to remove an interface by prefixing it with an
exclamation mark. It is possible to allow an interface by
prefixing it with two exclamation marks. An allowed interface beats
a forbidden interface which beats a simple matched interface. For
example, with
.Em eth*,!eth1,!eth2
.Nm
will only use interfaces starting with
.Em eth
with the exception of
.Em eth1
and
.Em eth2 .
While with
.Em *,!eth*,!!eth1
.Nm
will use all interfaces, except interfaces starting with
.Em eth
with the exception of
.Em eth1 .
When an exact match is found, it will circumvent some tests. For example, if
.Em eth0.12
is specified, it will be accepted even if this is a VLAN interface.
.It Fl C Ar interfaces
Specify which interfaces to use for computing chassis ID. Without this
option, all interfaces are considered.
.Nm
will take the first MAC address from all the considered interfaces
to compute the chassis ID. The logic of this option is the same as for
.Fl I
flag: you can exclude interfaces with an exclamation mark and use
globbing to specify several interfaces. If all interfaces are
removed (with
.Em !* ) ,
the system name is used as a chassis ID instead.
.It Fl M Ar class
Enable emission of LLDP-MED frames. Depending on the selected class,
the standard defines which set of TLV should be transmitted. See
section 10.2.1. Some devices may be strict in this aspect. The
class should be one of the following values:
.Bl -tag -width "0:XX" -compact
.It Sy 1
Generic Endpoint (Class I)
.It Sy 2
Media Endpoint (Class II). In this case, the standard requires to
define at least one network policy via
.Nm lldpcli .
.It Sy 3
Communication Device Endpoints (Class III). In this case, the standard
requires to define at least one network policy via
.Nm lldpcli .
.It Sy 4
Network Connectivity Device
.El
.It Fl i
Disable LLDP-MED inventory TLV transmission.
.Nm
will still receive (and publish using SNMP if enabled) those LLDP-MED
TLV but will not send them. Use this option if you don't want to
transmit sensitive information like serial numbers.
.It Fl H Ar hide
Filter neighbors. See section
.Sx FILTERING NEIGHBORS
for details.
.It Fl L Ar lldpcli
Provide an alternative path to
.Nm lldpcli
for configuration. If empty, does not use
.Nm lldpcli
for configuration.
.It Fl O Ar configfile
Override default configuration locations processed by
.Nm lldpcli
at start. If a directory is provided, each file therein suffixed with
.Sy .conf.
will be read. Order is alphabetical.
.It Fl v
Show
.Nm
version. When repeated, show more build information.
.El
.Sh FILTERING NEIGHBORS
In a heterogeneous network, you may see several different hosts on the
same port, even if there is only one physically plugged to this
port. For example, if you have a Nortel switch running LLDP which is
plugged to a Cisco switch running CDP and your host is plugged to the
Cisco switch, you will see the Nortel switch as well because LLDP
frames are forwarded by the Cisco switch. This may not be what you
want. The
.Fl H Ar hide
parameter allows you to tell
.Nm
to discard some frames that it receives and to avoid sending some
other frames.
.Pp
Incoming filtering and outgoing filtering are
unrelated. Incoming filtering will hide some remote ports to give you a
chance to know exactly what equipment is on the other side of the
link. Outgoing filtering will avoid using some protocols to
avoid flooding your network with a protocol that is not handled by the
nearest equipment. Keep in mind that even without filtering,
.Nm
will speak protocols for which at least one frame has been received
and LLDP otherwise (there are other options to change this behaviour,
for example
.Fl cc , ss , ee , ll
and
.Fl ff
).
.Pp
When enabling incoming filtering,
.Nm
will try to select one protocol, and filter out neighbors using other
protocols. To select this protocol, the rule is to take the less used
protocol. If on one port, you get 12 CDP neighbors and 1 LLDP
neighbor, this means that the remote switch speaks LLDP and does not
filter CDP. Therefore, we select LLDP. When enabling outgoing
filtering,
.Nm
will also try to select one protocol and only speak this
protocol. The filtering is done per port. Each port may select a
different protocol.
.Pp
There are two additional criteria when enabling filtering: allowing
one or several protocols to be selected (in case of a tie) and
allowing one or several neighbors to be selected. Even when allowing
several protocols, the rule of selecting the protocols with the fewest
neighbors still applies. If
.Nm
selects LLDP and CDP, this means they have the same number of
neighbors. The selection of the neighbor is random. Incoming filtering
will select a set of neighbors to be displayed while outgoing
filtering will use the selected set of neighbors to decide which
protocols to use: if a selected neighbor speaks LLDP and another one
CDP,
.Nm
will speak both CDP and LLDP on this port.
.Pp
There are some corner cases. A typical example is a switch speaking
two protocols (CDP and LLDP for example). You want to get the
information from the best protocol but you want to speak both
protocols because some tools use the CDP table and some other the LLDP
table.
.Pp
The table below summarizes all accepted values for the
.Fl H Ar hide
parameter. The default value is
.Em 15
which corresponds to the corner case described above. The
.Em filter
column means that filtering is enabled. The
.Em 1proto
column tells that only one protocol will be kept. The
.Em 1neigh
column tells that only one neighbor will be kept.
.Pp
.Bl -column -compact -offset indent "HXXX" "filterX" "1protoX" "1neighX" "filterX" "1protoX" "1neighX"
.It Ta Ta incoming Ta Ta outgoing Ta
.It Ta Em filter Ta Em 1proto Ta Em 1neigh Ta Em filter Ta Em 1proto Ta Em 1neigh
.It Em 0  Ta   Ta   Ta   Ta   Ta   Ta  
.It Em 1  Ta x Ta x Ta   Ta x Ta x Ta  
.It Em 2  Ta x Ta x Ta   Ta   Ta   Ta  
.It Em 3  Ta   Ta   Ta   Ta x Ta x Ta  
.It Em 4  Ta x Ta   Ta   Ta x Ta   Ta  
.It Em 5  Ta x Ta   Ta   Ta   Ta   Ta  
.It Em 6  Ta   Ta   Ta   Ta x Ta   Ta  
.It Em 7  Ta x Ta x Ta x Ta x Ta x Ta  
.It Em 8  Ta x Ta x Ta x Ta   Ta   Ta  
.It Em 9  Ta x Ta   Ta x Ta x Ta x Ta  
.It Em 10 Ta   Ta   Ta   Ta x Ta   Ta x
.It Em 11 Ta x Ta   Ta x Ta   Ta   Ta  
.It Em 12 Ta x Ta   Ta x Ta x Ta   Ta x
.It Em 13 Ta x Ta   Ta x Ta x Ta   Ta  
.It Em 14 Ta x Ta x Ta   Ta x Ta   Ta x
.It Em 15 Ta x Ta x Ta   Ta x Ta   Ta  
.It Em 16 Ta x Ta x Ta x Ta x Ta   Ta x
.It Em 17 Ta x Ta x Ta x Ta x Ta   Ta  
.It Em 18 Ta x Ta   Ta   Ta x Ta   Ta x
.It Em 19 Ta x Ta   Ta   Ta x Ta x Ta  
.El
.Sh FILES
.Bl -tag -width "@LLDPD_CTL_SOCKET@XX" -compact
.It @LLDPD_CTL_SOCKET@
Unix-domain socket used for communication with
.Xr lldpctl 8 .
.It @sysconfdir@/lldpd.conf
Configuration file for
.Nm .
Commands in this files are executed by
.Xr lldpcli 8
at start.
.It @sysconfdir@/lldpd.d
Directory containing configuration files whose commands are executed
by
.Xr lldpcli 8
at start.
.El
.Sh SEE ALSO
.Xr lldpctl 8 ,
.Xr lldpcli 8 ,
.Xr snmpd 8
.Sh HISTORY
The
.Nm
program is inspired from a preliminary work of Reyk Floeter.
.Sh AUTHORS
.An -nosplit
The
.Nm
program was written by
.An Pierre-Yves Ritschard Aq pyr@openbsd.org ,
and
.An Vincent Bernat Aq bernat@luffy.cx .