Merge pull request #2218 from vyos/mergify/bp/circinus/pr-2192

 docs: Update LLDP page to VyOS 1.5 standards (backport #2192)

1 files changed, 221 insertions, 105 deletions

diff --git a/docs/configuration/service/lldp.md b/docs/configuration/service/lldp.md
index 7fdba6c8..c555376a 100644
--- a/docs/configuration/service/lldp.md
+++ b/docs/configuration/service/lldp.md
@@ -1,154 +1,270 @@
+---
+myst:
+  html_meta:
+    description: |
+      LLDP is a vendor-neutral Layer 2 protocol that lets devices
+      advertise their identity, capabilities, and management addresses
+      to directly connected neighbors and learn the same from them.
+    keywords: lldp, lldp-med, cdp, edp, fdp, sonmp, neighbor-discovery
+---
+
 (lldp)=
 
 # LLDP
 
-{abbr}`LLDP (Link Layer Discovery Protocol)` is a vendor-neutral link layer
-protocol in the Internet Protocol Suite used by network devices for advertising
-their identity, capabilities, and neighbors on an IEEE 802 local area network,
-principally wired Ethernet. The protocol is formally referred to by the IEEE
-as Station and Media Access Control Connectivity Discovery specified in IEEE
-802.1AB and IEEE 802.3-2012 section 6 clause 79.
-
-LLDP performs functions similar to several proprietary protocols, such as
-{abbr}`CDP (Cisco Discovery Protocol)`,
-{abbr}`FDP (Foundry Discovery Protocol)`,
-{abbr}`NDP (Nortel Discovery Protocol)` and {abbr}`LLTD (Link Layer Topology
-Discovery)`.
-
-Information gathered with LLDP is stored in the device as a {abbr}`MIB
-(Management Information Database)` and can be queried with {abbr}`SNMP (Simple
-Network Management Protocol)` as specified in {rfc}`2922`. The topology of an
-LLDP-enabled network can be discovered by crawling the hosts and querying this
-database. Information that may be retrieved include:
-
-- System Name and Description
+{abbr}`LLDP (Link Layer Discovery Protocol)` is a vendor-neutral Layer
+2 protocol that enables devices to advertise their identity,
+capabilities, and management addresses to directly connected neighbors
+and to learn the same information from them. LLDP is specified in IEEE
+802.1AB, Station and Media Access Control Connectivity Discovery.
+
+Each device sends LLDP frames periodically on every interface where
+LLDP transmission is enabled and records the received information in a
+local neighbor database. This database can also be queried with
+{abbr}`SNMP (Simple Network Management Protocol)` (see `set service
+lldp snmp`), so the topology of an entire LLDP-enabled network can be
+mapped by querying each device in turn. Advertised information may
+include:
+
+- System name and description
 - Port name and description
 - VLAN name
-- IP management address
-- System capabilities (switching, routing, etc.)
-- MAC/PHY information
-- MDI power
-- Link aggregation
+- Management IP address
+- System capabilities (the device's role: router, bridge, telephone,
+  and so on)
+- Physical link settings, such as speed, duplex, and auto-negotiation
+  (MAC/PHY)
+- Power over Ethernet (MDI power)
+- Link aggregation (bonding)
+
+LLDP provides functionality similar to proprietary protocols such as
+{abbr}`CDP (Cisco Discovery Protocol)`,
+{abbr}`EDP (Extreme Discovery Protocol)`,
+{abbr}`FDP (Foundry Discovery Protocol)`, and
+{abbr}`SONMP (SynOptics Network Management Protocol)`. You can
+configure VyOS to interoperate with devices running these protocols
+via `set service lldp legacy-protocols`.
 
 ## Configuration
 
 ```{cfgcmd} set service lldp
 
-Enable LLDP service
+**Enable the LLDP service.**
+
+With no further configuration, the service sends and processes LLDP
+frames on every available local interface.
+
+Configure `service lldp interface` to restrict it to selected
+interfaces.
 ```
 
-```{cfgcmd} set service lldp management-address \<address\>
+Example:
 
-Define IPv4/IPv6 management address transmitted via LLDP. Multiple addresses
-can be defined. Only addresses connected to the system will be transmitted.
+```none
+set service lldp
 ```
 
 ```{cfgcmd} set service lldp interface \<interface\>
 
-Enable transmission of LLDP information on given \<interface\>. You can also
-say ``all`` here so LLDP is turned on on every interface.
+**Enable LLDP on the specified interface.**
+
+Repeat the command to enable LLDP on multiple interfaces. The special
+value `all` enables LLDP on every available local interface.
+
+Once LLDP is enabled with `set service lldp`, it runs on all available
+local interfaces by default. Configuring one or more interfaces here
+limits LLDP strictly to those configured, disabling LLDP on all
+remaining interfaces.
+```
+
+Example:
+
+```none
+set service lldp interface eth1
+set service lldp interface eth2
+```
+
+```{cfgcmd} set service lldp interface \<interface\> mode \<disable | rx-tx | tx | rx\>
+
+**Configure the LLDP administrative status on the specified
+interface:**
+
+- `rx-tx`: Sends LLDP frames and processes received ones.
+- `rx`: Processes only received frames, so the router learns about its
+  neighbors without announcing itself.
+- `tx`: Sends frames only.
+- `disable`: Neither sends nor processes frames on the interface.
+
+The default is `rx-tx`.
 ```
 
-```{cfgcmd} set service lldp interface \<interface\> mode [disable|rx-tx|rx|tx]
+Example:
 
-Configure the administrative status of the given port.
+```none
+set service lldp interface eth1 mode rx
+```
+
+```{cfgcmd} set service lldp interface \<interface\> location coordinate-based latitude \<latitude\>
+
+**Configure the latitude of the coordinate-based LLDP-MED location
+advertised on the specified interface.**
+
+The value is a decimal number followed by N or S. Both latitude and
+longitude must be configured.
+```
+
+Example:
+
+```none
+set service lldp interface eth1 location coordinate-based latitude 37.524449N
+```
+
+```{cfgcmd} set service lldp interface \<interface\> location coordinate-based longitude \<longitude\>
+
+**Configure the longitude of the coordinate-based LLDP-MED location
+advertised on the specified interface.**
+
+The value is a decimal number followed by E or W. Both latitude and
+longitude must be configured.
+```
+
+Example:
+
+```none
+set service lldp interface eth1 location coordinate-based longitude 122.267255W
+```
+
+```{cfgcmd} set service lldp interface \<interface\> location coordinate-based altitude \<altitude\>
+
+**Configure the altitude, in meters, of the coordinate-based LLDP-MED
+location advertised on the specified interface.**
+
+The value is a positive or negative number of meters, where 0 means no
+altitude. Altitude is part of the coordinate-based location, so
+latitude and longitude must also be configured for it to be
+advertised.
+
+The default is 0.
+```
 
-By default, all ports are configured to be in rx-tx mode. This means they
-can receive and transmit LLDP frames.
+Example:
 
-In rx mode, they won't emit any frames. In tx mode, they won't receive
-any frames. In disabled mode, no frame will be sent and any incoming frame
-will be discarded.
+```none
+set service lldp interface eth1 location coordinate-based altitude 12
+```
+
+```{cfgcmd} set service lldp interface \<interface\> location coordinate-based datum \<WGS84 | NAD83 | MLLW\>
+
+**Configure the geodetic datum of the coordinate-based LLDP-MED
+location advertised on the specified interface:**
+
+- `WGS84` and `NAD83` select the corresponding geodetic datum.
+- `MLLW` selects NAD83 combined with the
+  {abbr}`MLLW (Mean Lower Low Water)` tidal datum, used where altitude
+  is referenced to tidal water level.
+
+The default is `WGS84`.
+```
+
+Example:
+
+```none
+set service lldp interface eth1 location coordinate-based datum NAD83
+```
+
+```{cfgcmd} set service lldp interface \<interface\> location elin \<number\>
+
+**Advertise an Emergency Call Service
+{abbr}`ELIN (Emergency Location Identification Number)` on the
+specified interface.**
+
+The value is 10 to 25 digits.
+```
+
+Example:
+
+```none
+set service lldp interface eth1 location elin 1234567890
+```
+
+```{cfgcmd} set service lldp management-address \<address\>
+
+**Advertise the specified IPv4 or IPv6 address to LLDP neighbors as a
+management address.**
+
+Repeat the command to advertise multiple addresses. VyOS generates a
+warning upon commit if the address is a loopback address or is not
+assigned to any interface.
+```
+
+Example:
+
+```none
+set service lldp management-address 192.0.2.1
+set service lldp management-address 2001:db8::1
 ```
 
 ```{cfgcmd} set service lldp snmp
 
-Enable SNMP queries of the LLDP database
+**Allow the LLDP database to be queried over SNMP.**
+
+Requires a configured SNMP service (see {ref}`snmp`). Otherwise, the
+commit fails.
 ```
 
-```{cfgcmd} set service lldp legacy-protocols \<cdp|edp|fdp|sonmp\>
+Example:
 
-Enable given legacy protocol on this LLDP instance. Legacy protocols include:
-* ``cdp`` - Listen for CDP for Cisco routers/switches
-* ``edp`` - Listen for EDP for Extreme routers/switches
-* ``fdp`` - Listen for FDP for Foundry routers/switches
-* ``sonmp`` - Listen for SONMP for Nortel routers/switches
+```none
+set service lldp snmp
 ```
 
+```{cfgcmd} set service lldp legacy-protocols \<cdp | edp | fdp | sonmp\>
 
-## Operation
+**Enable the LLDP service to process the specified vendor-proprietary
+discovery protocol:**
 
-```{opcmd} show lldp neighbors
+- `cdp`: Cisco routers and switches.
+- `edp`: Extreme routers and switches.
+- `fdp`: Foundry routers and switches.
+- `sonmp`: Nortel routers and switches.
 
-Displays information about all neighbors discovered via LLDP.
+After receiving a frame of an enabled protocol on an interface, VyOS
+also transmits that protocol on the interface.
 
-:::{code-block} none
-vyos@vyos:~$ show lldp neighbors
-Capability Codes: R - Router, B - Bridge, W - Wlan r - Repeater, S - Station
-                  D - Docsis, T - Telephone, O - Other
+Repeat the command to enable processing of multiple protocols.
+```
 
-Device ID                 Local     Proto  Cap   Platform             Port ID
----------                 -----     -----  ---   --------             -------
-BR2.vyos.net              eth0      LLDP   R     VyOS 1.2.4           eth1
-BR3.vyos.net              eth0      LLDP   RB    VyOS 1.2.4           eth2
-SW1.vyos.net              eth0      LLDP   B     Cisco IOS Software   GigabitEthernet0/6
-:::
+Example:
+
+```none
+set service lldp legacy-protocols cdp
+```
+
+## Operation
+
+```{opcmd} show lldp neighbors
+
+**Show all neighbors discovered via LLDP or enabled legacy
+protocols.**
 ```
 
 ```{opcmd} show lldp neighbors detail
 
-Get detailed information about LLDP neighbors.
-
-:::{code-block} none
-vyos@vyos:~$ show lldp neighbors detail
--------------------------------------------------------------------------------
-LLDP neighbors:
--------------------------------------------------------------------------------
-Interface:    eth0, via: LLDP, RID: 28, Time: 0 day, 00:24:33
-Chassis:
-  ChassisID:    mac 00:53:00:01:02:c9
-  SysName:      BR2.vyos.net
-  SysDescr:     VyOS 1.3-rolling-201912230217
-  MgmtIP:       192.0.2.1
-  MgmtIP:       2001:db8::ffff
-  Capability:   Bridge, on
-  Capability:   Router, on
-  Capability:   Wlan, off
-  Capability:   Station, off
-Port:
-  PortID:       mac 00:53:00:01:02:c9
-  PortDescr:    eth0
-  TTL:          120
-  PMD autoneg:  supported: no, enabled: no
-      MAU oper type: 10GigBaseCX4 - X copper over 8 pair 100-Ohm balanced cable
-VLAN:         201 eth0.201
-VLAN:         205 eth0.205
-LLDP-MED:
-  Device Type:  Network Connectivity Device
-  Capability:   Capabilities, yes
-  Capability:   Policy, yes
-  Capability:   Location, yes
-  Capability:   MDI/PSE, yes
-  Capability:   MDI/PD, yes
-  Capability:   Inventory, yes
-  Inventory:
-      Hardware Revision: None
-      Software Revision: 4.19.89-amd64-vyos
-      Firmware Revision: 6.00
-      Serial Number: VMware-42 1d 83 b9 fe c1 bd b2-7
-      Manufacturer: VMware, Inc.
-      Model:        VMware Virtual Platform
-      Asset ID:     No Asset Tag
--------------------------------------------------------------------------------
-:::
+**Show detailed information about discovered neighbors.**
 ```
 
 ```{opcmd} show lldp neighbors interface \<interface\>
 
-Show LLDP neighbors connected via interface \<interface\>.
+**Show neighbors discovered on the specified interface.**
+```
+
+```{opcmd} show lldp neighbors interface \<interface\> detail
+
+**Show detailed information about neighbors discovered on the
+specified interface.**
 ```
 
 ```{opcmd} show log lldp
 
-Used for troubleshooting.
-```
\ No newline at end of file
+**Show the log of the LLDP service since the last boot.**
+```