diff options
Diffstat (limited to 'src/daemon/lldpd.8.in')
| -rw-r--r-- | src/daemon/lldpd.8.in | 424 |
1 files changed, 424 insertions, 0 deletions
diff --git a/src/daemon/lldpd.8.in b/src/daemon/lldpd.8.in new file mode 100644 index 0000000..32d57a6 --- /dev/null +++ b/src/daemon/lldpd.8.in @@ -0,0 +1,424 @@ +.\" 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 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 and send LLDPDU to. 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 by +.Em eth +with the exception of +.Em eth1 +and +.Em eth2 . +While with +.Em *,!eth*,!!eth1 +.Nm +will use all interfaces, except interfaces starting by +.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 frame. 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 about this aspect. The +class should be one of the following value: +.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 through +.Nm lldpcli . +.It Sy 3 +Communication Device Endpoints (Class III). In this case, the standard +requires to define at least one network policy through +.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 sensible 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 contained in it will be read if ending by +.Sy .conf. +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 will allow you to tell +.Nm +to discard some frames that it receives and to avoid to send some +other frames. +.Pp +Incoming filtering and outgoing filtering are +unrelated. Incoming filtering will hide some remote ports to get you a +chance to know exactly what equipment is on the other side of the +network cable. Outgoing filtering will avoid to use 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 mean 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 speaks 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 less +neighbors still apply. 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 summarize 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 . |