1 .\" Copyright (c) 2006 Pierre-Yves Ritschard <pyr@openbsd.org>
2 .\" Copyright (c) 2008 Vincent Bernat <bernat@luffy.cx>
4 .\" Permission to use, copy, modify, and/or distribute this software for any
5 .\" purpose with or without fee is hereby granted, provided that the above
6 .\" copyright notice and this permission notice appear in all copies.
8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16 .Dd $Mdocdate: July 16 2008 $
22 .Nd control LLDP daemon
42 When no command is specified,
44 will start an interactive shell which can be used to input arbitrary
45 commands as if they were specified on the command line. This
46 interactive shell should provide completion and history support.
48 The options are as follows:
51 Enable more debugging information. This flag can be repeated.
53 Specify the Unix-domain socket used for communication with
58 version. When repeated, show more build information.
60 Choose the output format. Currently
67 formats are available. The default is
72 but the structure of the JSON object is not affected by the number of
73 interfaces or the number of neighbors. It is therefore easier to
76 Read the given configuration file. This option may be repeated several
77 times. If a directory is provided, each file contained in it will be
80 Order is alphabetical.
86 will display detailed information about each neighbors on the
87 specified interfaces or on all interfaces if none are specified. This
88 command is mostly kept for backward compatibility with older versions.
90 The following commands are supported by
92 When there is no ambiguity, the keywords can be abbreviated. For
94 .Cd show neighbors ports eth0 summary
96 .Cd sh neigh p eth0 sum
98 .Bd -ragged -offset XX
100 .Bd -ragged -offset XXXXXX
106 .Bd -ragged -offset XXXXXX
107 Display general help or help about a command. Also, you can get help
108 using the completion or by pressing the
110 key. However, completion and inline help may be unavailable if
112 was compiled without readline support but
114 command is always available.
118 .Op ports Ar ethX Op ,...
119 .Op Cd details | summary
121 .Bd -ragged -offset XXXXXX
122 Display information about each neighbor known by
126 only the name and the port description of each remote host will be
127 displayed. On the other hand, with
129 all available information will be displayed, giving a verbose
132 also display remote ports hidden by the smart filter. When specifying
133 one or several ports, the information displayed is limited to the
138 .Op ports Ar ethX Op ,...
139 .Op Cd details | summary
141 .Bd -ragged -offset XXXXXX
142 Display information about each local interface known by
146 only the name and the port description of each local interface will be
147 displayed. On the other hand, with
149 all available information will be displayed, giving a verbose
152 also display local ports hidden by the smart filter. When specifying
153 one or several ports, the information displayed is limited to the
158 .Op Cd details | summary
159 .Bd -ragged -offset XXXXXX
160 Display information about local chassis. With
162 most details are skipped. On the other hand, with
164 all available information will be displayed, giving a verbose
169 .Op ports Ar ethX Op ,...
170 .Op Cd details | summary
173 .Bd -ragged -offset XXXXXX
174 Watch for any neighbor changes and report them as soon as they
175 happen. When specifying ports, the changes are only reported when
176 happening on the given ports.
180 have the same meaning than previously described. If
184 will exit after receiving the specified number of events.
187 .Cd show configuration
188 .Bd -ragged -offset XXXXXX
189 Display global configuration of
195 .Op ports Ar ethX Op ,...
197 .Bd -ragged -offset XXXXXX
198 Report LLDP-related statistics, like the number of LLDPDU transmitted,
199 received, discarded or unrecognized. When specifying ports, only the
200 statistics from the given port are reported. With
202 the statistics of each port is summed.
206 .Bd -ragged -offset XXXXXX
209 update its information and send new LLDP PDU on all interfaces.
213 .Cd system hostname Ar name
214 .Bd -ragged -offset XXXXXX
215 Override system hostname with the provided value. By default, the
216 system name is the FQDN found from the resolved value of
218 As a special value, use "." (dot) to use the short hostname instead of
224 .Bd -ragged -offset XXXXXX
225 Do not override system hostname and restore the use of the node name.
229 .Cd system description Ar description
230 .Bd -ragged -offset XXXXXX
231 Override chassis description with the provided value instead of using
232 kernel name, node name, kernel version, build date and architecture.
236 .Cd system description
237 .Bd -ragged -offset XXXXXX
238 Do not override chassis description and use a value computed from node
239 name, kernel name, kernel version, build date and architecture instead.
243 .Cd system chassisid Ar description
244 .Bd -ragged -offset XXXXXX
245 Override chassis ID with the provided value instead of using MAC address
246 from one interface or host name.
251 .Bd -ragged -offset XXXXXX
252 Do not override chassis ID and use a value computed from one of the interface
253 MAC address (or host name if none is found).
257 .Cd system platform Ar description
258 .Bd -ragged -offset XXXXXX
259 Override platform description with the provided value instead of using
260 kernel name. This value is currently only used for CDP.
265 .Bd -ragged -offset XXXXXX
266 Do not override platform description and use the kernel name. This
267 option undoes the previous one.
271 .Cd system interface pattern Ar pattern
272 .Bd -ragged -offset XXXXXX
273 Specify which interface to listen and send LLDPDU to. Without this
276 will use all available physical interfaces. This option can use
277 wildcards. Several interfaces can be specified separated by commas.
278 It is also possible to blacklist an interface by suffixing it with an
279 exclamation mark. It is possible to whitelist an interface by
280 suffixing it with two exclamation marks. A whitelisted interface beats
281 a blacklisted interfaces which beats a simple matched interface. For
285 will only use interfaces starting by
287 with the exception of
294 will use all interfaces, except interfaces starting by
296 with the exception of
298 When an exact match is found, it will circumvent some tests. For example, if
300 is specified, it will be accepted even if this is a VLAN interface.
304 .Cd system interface pattern
305 .Bd -ragged -offset XXXXXX
306 Remove any previously configured interface pattern and use all
307 physical interfaces. This option undoes the previous one.
311 .Cd system interface permanent Ar pattern
312 .Bd -ragged -offset XXXXXX
313 Specify interfaces whose configuration is permanently kept by
317 disregard any data about interfaces when they are removed from the
318 system (statistics, custom configuration). This option allows one to
319 specify a pattern similar to the interface pattern. If an interface
320 disappear but matches the pattern, its data is kept in memory and
321 reused if the interface reappear at some point. For example, on Linux,
322 one could use the pattern
324 which should match fixed interfaces on most systems.
328 .Cd system interface permanent
329 .Bd -ragged -offset XXXXXX
330 Remove any previously configured permanent interface pattern. Any
331 interface removed from the system will be forgotten. This option
332 undoes the previous one.
336 .Cd system interface description
337 .Bd -ragged -offset XXXXXX
338 Some OS allows the user to set a description for an interface. Setting
339 this option will enable
341 to override this description with the name of the peer neighbor if one
342 is found or with the number of neighbors found.
346 .Cd system interface description
347 .Bd -ragged -offset XXXXXX
348 Do not update interface description with the name of the peer
349 neighbor. This option undoes the previous one.
353 .Cd system interface promiscuous
354 .Bd -ragged -offset XXXXXX
355 Enable promiscuous mode on managed interfaces.
357 When the interface is not managed any more (or when quitting
359 the interface is left in promiscuous mode as it is difficult to know
360 if someone else also put the interface in promiscuous mode.
362 This option is known to be useful when the remote switch is a Cisco
363 2960 and the local network card features VLAN hardware
364 acceleration. In this case, you may not receive LLDP frames from the
365 remote switch. The most plausible explanation for this is the frame is
366 tagged with some VLAN (usually VLAN 1) and your network card is
367 filtering VLAN. This is not the only available solution to work-around
368 this problem. If you are concerned about performance issues, you can
369 also tag the VLAN 1 on each interface instead.
371 Currently, this option has no effect on anything else than Linux. On
372 other OS, either disable VLAN acceleration, tag VLAN 1 or enable
373 promiscuous mode manually on the interface.
377 .Cd system interface promiscuous
378 .Bd -ragged -offset XXXXXX
379 Do not set promiscuous mode on managed interfaces. This option does
380 not disable promiscuous mode on interfaces already using this mode.
384 .Cd system ip management pattern Ar pattern
385 .Bd -ragged -offset XXXXXX
386 Specify the management addresses of this system. As for interfaces
387 (described above), this option can use wildcards and inversions.
388 Without this option, the first IPv4 and the first IPv6 are used. If an
389 exact IP address is provided, it is used as a management address
390 without any check. If only negative patterns are provided, only one
391 IPv4 and one IPv6 addresses are chosen. Otherwise, many of them can be
392 selected. If you want to blacklist IPv6 addresses, you can use
394 If an interface name is matched, the first IPv4 address and the first
395 IPv6 address associated to this interface will be chosen.
399 .Cd system ip management pattern
400 .Bd -ragged -offset XXXXXX
401 Unset any specific pattern for matching management addresses. This
402 option undoes the previous one.
406 .Cd system bond-slave-src-mac-type Ar value
407 .Bd -ragged -offset XXXXXX
408 Set the type of src mac in lldp frames sent on bond slaves
411 .Bl -tag -width "XXX." -compact -offset XX
417 An arbitrary fixed value
418 .Li ( 00:60:08:69:97:ef )
420 Real mac with locally administered bit set. If the real mac already
421 has the locally administered bit set, fallback to the fixed value.
425 .Nm bond-slave-src-mac-type
428 Some switches may complain when using one of the two other possible
429 values (either because
430 .Li 00:00:00:00:00:00
431 is not a valid MAC or because the MAC address is flapping from one
432 port to another). Using
434 might lead to a duplicate MAC address on the network (but this is
439 .Cd system max-neighbors Ar neighbors
440 .Bd -ragged -offset XXXXXX
441 Change the maximum number of neighbors accepted (for each protocol) on
442 an interface. This is a global value. The default is 32. This setting
443 only applies to future neighbors.
448 .Cd nearest-bridge | nearest-non-tpmr-bridge | nearest-customer-bridge
449 .Bd -ragged -offset XXXXXX
450 The destination MAC address used to send LLDPDU allows an agent to
451 control the propagation of LLDPDUs. By default, the
452 .Li 01:80:c2:00:00:0e
453 MAC address is used and limit the propagation of the LLDPDU to the
455 .Cd ( nearest-bridge ) .
459 .Li 01:80:c2:00:00:03
460 MAC address instead, use
461 .Cd nearest-nontpmr-bridge
464 .Li 01:80:c2:00:00:00
465 MAC address instead, use
466 .Cd nearest-customer-bridge
471 .Cd lldp portidsubtype
472 .Cd ifname | macaddress
475 .Op ports Ar ethX Op ,...
476 .Cd lldp portidsubtype
478 .Bd -ragged -offset XXXXXX
479 Force port ID subtype. By default,
481 will use the MAC address as port identifier and the interface name as
482 port description, unless the interface has an alias. In this case, the
483 interface name will be used as port identifier and the description
484 will be the interface alias. With this command, you can force the port
485 identifier to be the interface name (with
487 the MAC address (with
489 or a local value (with
491 In the latest case, the local value should be provided.
495 .Op ports Ar ethX Op ,...
496 .Cd lldp portdescription
498 .Bd -ragged -offset XXXXXX
499 Force port description to the provided string.
503 .Cd lldp tx-interval Ar interval
504 .Bd -ragged -offset XXXXXX
505 Change transmit delay to the specified value in seconds. The transmit
506 delay is the delay between two transmissions of LLDP PDU. The default
507 value is 30 seconds. Note:
509 also starts another system based refresh timer on each port to detect
510 changes such as a hostname. This is the value of the tx-interval
515 .Cd lldp tx-hold Ar hold
516 .Bd -ragged -offset XXXXXX
517 Change transmit hold value to the specified value. This value is used
518 to compute the TTL of transmitted packets which is the product of this
519 value and of the transmit delay. The default value is 4 and therefore
520 the default TTL is 120 seconds.
524 .Op ports Ar ethX Op ,...
526 .Cd status Ar rx-and-tx | rx-only | tx-only | disabled
527 .Bd -ragged -offset XXXXXX
528 Configure the administrative status of the given port. By default, all
529 ports are configured to be in
531 mode. This means they can receive and transmit LLDP frames (as well as
532 other protocols if needed). In
534 mode, they won't emit any frames and in
536 mode, they won't receive any frames. In
538 mode, no frame will be sent and any incoming frame will be
539 discarded. This setting does not override the operational mode of the
540 main daemon. If it is configured in receive-only mode (with the
542 flag), setting any transmit mode won't have any effect.
549 .Cd subtype Ar subtype
550 .Op Cd oui-info Ar content
551 .Bd -ragged -offset XXXXXX
552 Emit a custom TLV for OUI
556 and optionally with the bytes specified in
562 should be a comma-separated list of bytes in hex format.
564 must be exactly 3-byte long.
567 is specified then the TLV will be added. This is the default action.
570 is specified then all TLVs with the same
581 .Op Cd subtype Ar subtype
582 .Bd -ragged -offset XXXXXX
583 When no oui is specified, remove all previously configured custom TLV.
588 is specified, remove specific instances of custom TLV.
591 .Cd configure med fast-start
592 .Cd enable | tx-interval Ar interval
593 .Bd -ragged -offset XXXXXX
594 Configure LLDP-MED fast start mechanism. When a new LLDP-MED-enabled
595 neighbor is detected, fast start allows
597 to shorten the interval between two LLDPDU.
599 should enable LLDP-MED fast start while
601 specifies the interval between two LLDPDU in seconds. The default
602 interval is 1 second. Once 4 LLDPDU have been sent, the fast start
603 mechanism is disabled until a new neighbor is detected.
606 .Cd unconfigure med fast-start
607 .Bd -ragged -offset XXXXXX
608 Disable LLDP-MED fast start mechanism.
612 .Op ports Ar ethX Op ,...
613 .Cd med location coordinate
614 .Cd latitude Ar latitude
615 .Cd longitude Ar longitude
616 .Cd altitude Ar altitude Ar unit
618 .Bd -ragged -offset XXXXXX
619 Advertise a coordinate based location on the given ports (or on all
620 ports if no port is specified). The format of
622 is a decimal floating point number followed either by
628 is a decimal floating point number followed either by
633 is a decimal floating point number followed either by
635 when expressed in meters or
637 when expressed in floors. A space is expected between the floating
638 point number and the unit.
640 is one of those values:
641 .Bl -bullet -compact -offset XXXXXXXX
650 A valid use of this command is:
651 .D1 configure ports eth0 med location coordinate latitude 48.85667N longitude 2.2014E altitude 117.47 m datum WGS84
655 .Op ports Ar ethX Op ,...
656 .Cd med location address
657 .Cd country Ar country
658 .Cd Op Ar type value Op ...
659 .Bd -ragged -offset XXXXXX
660 Advertise a civic address on the given ports (or on all ports if no
663 is the two-letter code representing the country. The remaining
664 arguments should be paired to form the address. The first member of
665 each pair indicates the type of the second member which is a free-form
666 text. Here is the list of valid types:
667 .Bl -bullet -compact -offset XXXXXXXX
685 trailing-street-suffix
714 A valid use of this command is:
715 .D1 configure ports eth1 med location address country US street Qo Commercial Road Qc city Qo Roseville Qc
719 .Op ports Ar ethX Op ,...
720 .Cd med location elin
722 .Bd -ragged -offset XXXXXX
723 Advertise the availability of an ELIN number. This is used for setting
724 up emergency call. If the provided number is too small, it will be
725 padded with 0. Here is an example of use:
726 .D1 configure ports eth2 med location elin 911
730 .Op ports Ar ethX Op ,...
732 .Cd application Ar application
736 .Op Cd priority Ar priority
738 .Bd -ragged -offset XXXXXX
739 Advertise a specific network policy for the given ports (or for all
740 ports if no port was provided). Only the application type is
743 should be one of the following values:
744 .Bl -bullet -compact -offset XXXXXXXX
752 guest-voice-signaling
765 flag tells that the network policy for the specified application type
766 is required by the device but is currently unknown. This is used by
767 Endpoint Devices, not by Network Connectivity Devices. If not
768 specified, the network policy for the given application type is
771 When a VLAN is specified with
773 tells which 802.1q VLAN ID has to be advertised for the network
774 policy. A valid value is between 1 and 4094.
776 tells the VLAN should be tagged for the specified application type.
779 allows one to specify IEEE 802.1d / IEEE 802.1p Layer 2 Priority, also
780 known as Class of Service (CoS), to be used for the specified
781 application type. This field is usually ignored if no VLAN is
782 specified. The names match 802.1D-2004 standard (table G-2). Some more
783 recent standards may use different labels. Only the numeric values
784 should be relied upon. The accepted labels are:
785 .Bl -tag -width "X." -compact -offset XXXX
793 critical-applications
805 represents the DSCP value to be advertised for the given network
806 policy. DiffServ/Differentiated Services Code Point (DSCP) value as
807 defined in IETF RFC 2474 for the specified application type. Value: 0
808 (default per RFC 2475) through 63. Note: The class selector DSCP
809 values are backwards compatible for devices that only support the old
810 IP precedence Type of Service (ToS) format. (See the RFCs for what
813 A valid use of this command is:
814 .D1 configure med policy application voice vlan 500 priority voice dscp 46
818 .Op ports Ar ethX Op ,...
819 .Cd med power pse | pd
821 .Cd priority Ar priority
823 .Bd -ragged -offset XXXXXX
824 Advertise the LLDP-MED POE-MDI TLV for the given ports or for all
825 interfaces if no port is provided. One can act as a PD (power
826 consumer) or a PSE (power provider). No check is done on the validity
827 of the parameters while LLDP-MED requires some restrictions:
830 PD shall never request more power than physical 802.3af class.
832 PD shall never draw more than the maximum power advertised by PSE.
834 PSE shall not reduce power allocated to PD when this power is in use.
836 PSE may request reduced power using conservation mode
838 Being PSE or PD is a global parameter, not a per-port parameter.
840 does not enforce this: a port can be set as PD or PSE. LLDP-MED also
841 requires for a PSE to only have one power source (primary or
844 does not enforce this. Each port can have its own power source. The
845 same applies for PD and power priority. LLDP-MED MIB does not allow
846 this kind of representation.
850 .Bl -tag -width "XXX." -compact -offset XX
852 Power Sourcing Entity (power provider)
854 Power Device (power consumer)
858 .Bl -tag -width "XXXXXXX" -compact -offset XX
862 For PSE, the power source is the primary power source.
864 For PSE, the power source is the backup power source or a power
865 conservation mode is asked (the PSE may be running on UPS for
868 For PD, the power source is the PSE.
870 For PD, the power source is a local source.
872 For PD, the power source is both the PSE and a local source.
875 Valid priorities are:
876 .Bl -tag -width "XXXXXXXXX" -compact -offset XX
888 should be the total power in milliwatts required by the PD device or
889 available by the PSE device.
891 Here is an example of use:
892 .D1 configure med power pd source pse priority high value 5000
896 .Op ports Ar ethX Op ,...
897 .Cd dot3 power pse | pd
901 .Op Cd powerpairs Ar powerpairs
902 .Op Cd class Ar class
903 .Op Cd type Ar type Cd source Ar source Cd priority Ar priority Cd requested Ar requested Cd allocated Ar allocated
904 .Bd -ragged -offset XXXXXX
905 Advertise Dot3 POE-MDI TLV for the given port or for all ports if none
906 was provided. One can act as a PD (power consumer) or a PSE (power
907 provider). This configuration is distinct of the configuration of the
908 transmission of the LLDP-MED POE-MDI TLV but the user should ensure
909 the coherency of those two configurations if they are used together.
912 means that MDI power is supported on the given port while
914 means that MDI power is enabled.
916 is used to indicate if pair selection can be controlled. Valid values
920 .Bl -tag -width "XXXXXX" -compact -offset XX
922 The signal pairs only are in use.
924 The spare pairs only are in use.
929 is a number between 0 and 4.
931 The remaining parameters are in conformance with 802.3at and are optional.
933 should be either 1 or 2, indicating which if the device conforms to
934 802.3at type 1 or 802.3at type 2. Values of
938 are the same as for LLDP-MED POE-MDI TLV.
942 are expressed in milliwats.
944 Here are two valid uses of this command:
945 .D1 configure ports eth3 dot3 power pse supported enabled paircontrol powerpairs spare class class-3
946 .D1 configure dot3 power pd supported enabled powerpairs spare class class-3 type 1 source pse priority low requested 10000 allocated 15000
950 .Bd -ragged -offset XXXXXX
955 will not send any more frames or receive ones. This can be undone with
961 .Bd -ragged -offset XXXXXX
966 will start to send and receive frames. This command is issued
967 internally after processing configuration but can be used at any time
975 .Bl -tag -width "@LLDPD_CTL_SOCKET@XX" -compact
976 .It @LLDPD_CTL_SOCKET@
977 Unix-domain socket used for communication with
986 program was written by
987 .An Vincent Bernat Aq bernat@luffy.cx .