CP-312082 Implement APIs for configuration of lldp (#7200)

Design doc:
https://github.com/xapi-project/xen-api/blob/master/doc/content/design/lldp.md

New fileds:
pool.lldp_enabled
pool.lldp_multicast_address (RW)
pif.lldp_mode

APIs:
pool.set_lldp_enabled
PIF.set_lldp_mode

CLI:
xe pool-set-lldp-enabled
xe pif-set-lldp-mode

Author: changlei-li

doc/content/design/lldp.md

@@ -22,7 +22,7 @@ The following are introduced by this design:
 The implementation uses XAPI for configuration, networkd for per-host application of configuration, and [`lldpd`](https://github.com/lldpd/lldpd) as the LLDP agent in dom0 user space.
 XAPI stores LLDP configuration in the database and exposes LLDP neighbor data through XenAPI.
 networkd configures the LLDP agent to apply LLDP configuration for individual physical NICs and queries the LLDP agent for received LLDP TLVs.
-`lldpd` runs as a daemon process in dom0 user space. It receives and sends LLDPDUs via PF_PACKET + SOCK_RAW sockets. It is actively maintained by upstream as the time being.
+`lldpd` runs as a daemon process in dom0 user space. It receives and sends LLDPDUs via PF_PACKET + SOCK_RAW sockets. It is actively maintained by upstream for the time being.
 
 ## XAPI database changes
 
@@ -37,7 +37,7 @@ When `false`, LLDP is disabled on the NIC associated with each managed physical
 
 This setting does not apply to other types of PIFs, such as non-managed PIFs, bond PIFs, VLAN PIFs, tunnel PIFs, or SR-IOV PIFs.
 
-`PIF.lldp_mode` determines the final effective state on individul PIF.
+`PIF.lldp_mode` determines the final effective state on individual PIF.
 
 LLDP receiving and advertising are always enabled or disabled together.
 
@@ -51,15 +51,15 @@ Type: `enum pif_lldp_mode`
 
 Values:
 
-- `default`: follow `pool.lldp_enabled`;
+- `inherited`: follow `pool.lldp_enabled`;
 - `enabled`: LLDP is enabled on the NIC associated with the managed physical PIF;
 - `disabled`: LLDP is disabled on the NIC associated with the managed physical PIF.
 
 This setting does not apply to other types of PIFs, such as non-managed PIFs, bond PIFs, VLAN PIFs, tunnel PIFs, or SR-IOV PIFs.
 
-Default after update/RPU from a version/release without LLDP support to a version/release with LLDP support: `default`.
+Default after update/RPU from a version/release without LLDP support to a version/release with LLDP support: `inherited`.
 
-Default after fresh install: `default`.
+Default after fresh install: `inherited`.
 
 ### `pool.lldp_multicast_address`
 
@@ -72,7 +72,7 @@ Values:
 - `nearestcustomerbridge`: `01:80:C2:00:00:00`
 
 This value controls the multicast MAC address used for LLDP transmission.
-After a change, it is applied when `pool.set_lldp_enabled` or `PIF.set_lldp_mode` is called with `force=true`.
+After a change, it is applied when `pool.set_lldp_enabled` or `PIF.set_lldp_mode` is called (can apply with `force=true` if enabled or mode is not changed).
 This value is not considered to change often. Changing it does not trigger any application action for simplicity.
 
 Default after update/RPU from a version/release without LLDP support to a version/release with LLDP support: `nearestbridge`.
@@ -110,7 +110,7 @@ Behavior:
 Parameters:
 
 - `self`: the PIF reference;
-- `value`: `default`, `enabled`, or `disabled`;
+- `value`: `inherited`, `enabled`, or `disabled`;
 - `force`: `bool`, default `false`.
 
 Behavior:
@@ -122,7 +122,7 @@ Behavior:
 ## The networkd database
 
 The `interface_config_t` record in the networkd database is extended with LLDP configuration. networkd can configure LLDP independently using its own database when XAPI is unavailable, for example during host boot.
-The default enabled setting is `false` to minimize impact without high-level configuration from XAPI or the user. This database can be updated as XAPI pushes configurtions to networkd through networkd calls.
+The default enabled setting is `false` to minimize impact without high-level configuration from XAPI or the user. This database can be updated as XAPI pushes configurations to networkd through networkd calls.
 
 ```ocaml
 type lldp_multicast_address =
@@ -136,8 +136,8 @@ type lldp = {
 ; chassis_id: string [@default ""]
 ; system_name: string [@default ""]
 ; system_description: string [@default ""]
-; enabled: bool [@default false];
-; address: lldp_multicast_address list [@default [Nearestbridge]];
+; enabled: bool [@default false]
+; address: lldp_multicast_address list [@default [Nearestbridge]]
 }
 [@@deriving rpcty]
 
@@ -172,9 +172,9 @@ The effective LLDP state on a NIC is determined by `pool.lldp_enabled`, `PIF.lld
 
 | `pool.lldp_enabled` | `PIF.lldp_mode` | parameter passed to networkd | NIC driver in blocking list | effective LLDP state |
 | --- | --- | --- | --- | --- |
-| `true` | `default` | `true` | `no` | `enabled` |
-| `true` | `default` | `true` | `yes` | `disabled` |
-| `false` | `default` | `false` | `*` | `disabled` |
+| `true` | `inherited` | `true` | `no` | `enabled` |
+| `true` | `inherited` | `true` | `yes` | `disabled` |
+| `false` | `inherited` | `false` | `*` | `disabled` |
 | `*` | `enabled` | `true` | `*` | `enabled` |
 | `*` | `disabled` | `false` | `*` | `disabled` |
 
@@ -212,7 +212,7 @@ type iface_stats = {
   lldp_neighbor: lldp_rx option;
 }
 ```
-networkd queries `lldpd` for the LLDP TLVs recevied on individual NICs and writes them into `/dev/shm/network_stats`.
+networkd queries `lldpd` for the LLDP TLVs received on individual NICs and writes them into `/dev/shm/network_stats`.
 Monitor_dbcalls.monitor_dbcall_thread in XAPI reads the in-memory file `/dev/shm/network_stats` periodically, and exposes the data through `PIF_metrics.lldp_neighbor` by storing them in XenAPI map form.
 
 ## Scenarios

ocaml/idl/datamodel.ml

@@ -2265,6 +2265,44 @@ module PIF = struct
       ~lifecycle:[(Published, rel_tampa, "")]
       ~allowed_roles:_R_POOL_OP ()
 
+  let lldp_mode =
+    Enum
+      ( "pif_lldp_mode"
+      , [
+          ( "inherited"
+          , "LLDP is enabled or disabled based on pool.lldp_enabled."
+          )
+        ; ( "enabled"
+          , "LLDP is enabled on the NIC of the managed physical PIF, \
+             overriding pool.lldp_enabled."
+          )
+        ; ( "disabled"
+          , "LLDP is disabled on the NIC of the managed physical PIF, \
+             overriding pool.lldp_enabled."
+          )
+        ]
+      )
+
+  let set_lldp_mode =
+    call ~name:"set_lldp_mode" ~lifecycle:[]
+      ~doc:
+        "Set the LLDP mode of this PIF, then apply the change by re-plugging \
+         the PIF. Only valid for managed physical PIFs."
+      ~params:
+        [
+          (Ref _pif, "self", "the PIF object to reconfigure")
+        ; ( lldp_mode
+          , "value"
+          , "the LLDP mode to set (inherited, enabled or disabled)"
+          )
+        ; ( Bool
+          , "force"
+          , "When true, apply the change even if value already matches the \
+             current PIF.lldp_mode; otherwise apply only when value differs."
+          )
+        ]
+      ~allowed_roles:_R_POOL_OP ()
+
   let scan =
     call ~name:"scan"
       ~doc:
@@ -2608,6 +2646,7 @@ module PIF = struct
         ; db_introduce
         ; db_forget
         ; set_property
+        ; set_lldp_mode
         ]
       ~contents:
         [
@@ -2891,6 +2930,11 @@ module PIF = struct
             ~lifecycle:[(Published, rel_kolkata, "")]
             ~default_value:(Some (VRef null_ref)) "PCI"
             "Link to underlying PCI device"
+        ; field ~qualifier:DynamicRO ~ty:lldp_mode ~lifecycle:[]
+            ~default_value:(Some (VEnum "inherited")) "lldp_mode"
+            "The LLDP mode of the physical NIC for the PIF. This setting does \
+             not apply to other types of PIFs, such as non-managed PIFs, bond \
+             PIFs, VLAN PIFs, tunnel PIFs, or SR-IOV PIFs."
         ]
       ()
 end

ocaml/idl/datamodel_pool.ml

@@ -1190,6 +1190,29 @@ let set_igmp_snooping_enabled =
     ~doc:"Enable or disable IGMP Snooping on the pool."
     ~allowed_roles:_R_POOL_OP ()
 
+let set_lldp_enabled =
+  call ~name:"set_lldp_enabled" ~lifecycle:[]
+    ~doc:
+      "Enable or disable LLDP on the NIC of every managed physical PIF in the \
+       pool, then apply the change by re-plugging the affected PIFs."
+    ~params:
+      [
+        (Ref _pool, "self", "The pool")
+      ; (Bool, "value", "true to enable LLDP, false to disable it")
+      ; ( Bool
+        , "force"
+        , "When true, apply the change to all managed physical PIFs even if \
+           value already matches pool.lldp_enabled; otherwise apply only when \
+           value differs from pool.lldp_enabled."
+        )
+      ]
+    ~result:
+      ( Map (Ref _pif, String)
+      , "A map of the PIFs that failed to be reconfigured and the \
+         corresponding error message."
+      )
+    ~allowed_roles:_R_POOL_OP ()
+
 let has_extension =
   call ~name:"has_extension"
     ~lifecycle:
@@ -1782,6 +1805,24 @@ let exchange_crls_on_join =
     ~allowed_roles:(_R_POOL_OP ++ _R_CLIENT_CERT)
     ~hide_from_docs:true ~lifecycle:[] ()
 
+let lldp_multicast_address =
+  Enum
+    ( "lldp_multicast_address"
+    , [
+        ( "nearestbridge"
+        , "Nearest bridge group address (MAC 01:80:C2:00:00:0E). LLDP frames \
+           reach only the immediate neighbor on the physical link."
+        )
+      ; ( "nearestnontpmrbridge"
+        , "Nearest non-TPMR (Two-Port MAC Relay) bridge group address (MAC \
+           01:80:C2:00:00:03)."
+        )
+      ; ( "nearestcustomerbridge"
+        , "Nearest customer bridge group address (MAC 01:80:C2:00:00:00)."
+        )
+      ]
+    )
+
 (** A pool class *)
 let t =
   create_obj ~in_db:true
@@ -1851,6 +1892,7 @@ let t =
       ; enable_ssl_legacy
       ; disable_ssl_legacy
       ; set_igmp_snooping_enabled
+      ; set_lldp_enabled
       ; has_extension
       ; add_to_guest_agent_config
       ; remove_from_guest_agent_config
@@ -2442,6 +2484,19 @@ let t =
              /import_metadata calls and disaster recovery (VM.recover and \
              VM_appliance.recover); it does not apply to VM.clone or VM.copy, \
              which inherit the source VM's state."
+        ; field ~qualifier:DynamicRO ~lifecycle:[] ~ty:Bool
+            ~default_value:(Some (VBool false)) "lldp_enabled"
+            "When true, LLDP is enabled on the NIC associated with each \
+             managed physical PIF on every host in the pool. When false, it is \
+             disabled. However, it can be overridden by PIF.lldp_mode settings \
+             when mode is not inherited. LLDP receiving and advertising are \
+             always enabled or disabled together."
+        ; field ~writer_roles:_R_POOL_OP ~qualifier:RW ~lifecycle:[]
+            ~ty:lldp_multicast_address
+            ~default_value:(Some (VEnum "nearestbridge"))
+            "lldp_multicast_address"
+            "The multicast MAC address used for LLDP advertising. To apply a \
+             change, use pool.set_lldp_enabled(with force=true)."
         ]
       )
     ()

ocaml/idl/schematest.ml

@@ -3,7 +3,7 @@ let hash x = Digest.string x |> Digest.to_hex
 (* BEWARE: if this changes, check that schema has been bumped accordingly in
    ocaml/idl/datamodel_common.ml, usually schema_minor_vsn *)
 
-let last_known_schema_hash = "b88f7174944ef37e6f2c53b5232465e9"
+let last_known_schema_hash = "e5bb3f3b53e89a81d7a7fcee7ead9efe"
 
 let current_schema_hash : string =
   let open Datamodel_types in

ocaml/tests/common/test_common.ml

@@ -338,7 +338,8 @@ let make_pool ~__context ~master ?(name_label = "") ?(name_description = "")
     ~ext_auth_cache_expiry:300L ~update_sync_frequency ~update_sync_day
     ~update_sync_enabled ~recommendations ~license_server
     ~ha_reboot_vm_on_internal_shutdown ~limit_console_sessions
-    ~vm_console_idle_timeout ~auto_update_vm_secureboot_certificates ;
+    ~vm_console_idle_timeout ~auto_update_vm_secureboot_certificates
+    ~lldp_enabled:false ~lldp_multicast_address:`nearestbridge ;
   pool_ref
 
 let default_sm_features =

ocaml/xapi-cli-server/cli_frontend.ml

@@ -498,6 +498,16 @@ let rec cmdtable_data : (string * cmd_spec) list =
       ; flags= []
       }
     )
+  ; ( "pool-set-lldp-enabled"
+    , {
+        reqd= ["value"]
+      ; optn= ["uuid"; "force"]
+      ; help=
+          "Enable or disable LLDP on every managed physical PIF in the pool."
+      ; implementation= No_fd Cli_operations.pool_set_lldp_enabled
+      ; flags= []
+      }
+    )
   ; ( "pool-set-vswitch-controller"
     , {
         reqd= ["address"]
@@ -2123,6 +2133,17 @@ let rec cmdtable_data : (string * cmd_spec) list =
       ; flags= []
       }
     )
+  ; ( "pif-set-lldp-mode"
+    , {
+        reqd= ["uuid"; "value"]
+      ; optn= ["force"]
+      ; help=
+          "Set the LLDP mode (inherited, enabled or disabled) of a managed \
+           physical PIF."
+      ; implementation= No_fd Cli_operations.pif_set_lldp_mode
+      ; flags= []
+      }
+    )
   ; ( "pif-scan"
     , {
         reqd= ["host-uuid"]

ocaml/xapi-cli-server/cli_operations.ml

@@ -1945,6 +1945,20 @@ let pool_disable_client_certificate_auth _printer rpc session_id params =
   let pool = get_pool_with_default rpc session_id params "uuid" in
   Client.Pool.disable_client_certificate_auth ~rpc ~session_id ~self:pool
 
+let pool_set_lldp_enabled printer rpc session_id params =
+  let pool = get_pool_with_default rpc session_id params "uuid" in
+  let value = bool_of_string "value" (List.assoc "value" params) in
+  let force = get_bool_param params "force" in
+  let failures =
+    Client.Pool.set_lldp_enabled ~rpc ~session_id ~self:pool ~value ~force
+  in
+  let table =
+    List.map
+      (fun (pif, msg) -> (Client.PIF.get_uuid ~rpc ~session_id ~self:pif, msg))
+      failures
+  in
+  printer (Cli_printer.PTable [table])
+
 let pool_sync_updates printer rpc session_id params =
   let pool = get_pool_with_default rpc session_id params "uuid" in
   let force = get_bool_param params "force" in
@@ -6711,6 +6725,14 @@ let pif_set_primary_address_type _printer rpc session_id params =
   in
   ()
 
+let pif_set_lldp_mode _printer rpc session_id params =
+  let pif =
+    Client.PIF.get_by_uuid ~rpc ~session_id ~uuid:(List.assoc "uuid" params)
+  in
+  let value = Record_util.pif_lldp_mode_of_string (List.assoc "value" params) in
+  let force = get_bool_param params "force" in
+  Client.PIF.set_lldp_mode ~rpc ~session_id ~self:pif ~value ~force
+
 let pif_unplug _printer rpc session_id params =
   let pif =
     Client.PIF.get_by_uuid ~rpc ~session_id ~uuid:(List.assoc "uuid" params)

ocaml/xapi-cli-server/records.ml

@@ -736,6 +736,11 @@ let pif_record rpc session_id pif =
               (x ()).API.pIF_igmp_snooping_status
           )
           ()
+      ; make_field ~name:"lldp-mode"
+          ~get:(fun () ->
+            Record_util.pif_lldp_mode_to_string (x ()).API.pIF_lldp_mode
+          )
+          ()
       ]
   }
 
@@ -1337,6 +1342,19 @@ let pool_record rpc session_id pool =
               ~value:(bool_of_string x)
           )
           ()
+      ; make_field ~name:"lldp-enabled"
+          ~get:(fun () -> string_of_bool (x ()).API.pool_lldp_enabled)
+          ()
+      ; make_field ~name:"lldp-multicast-address"
+          ~get:(fun () ->
+            Record_util.lldp_multicast_address_to_string
+              (x ()).API.pool_lldp_multicast_address
+          )
+          ~set:(fun v ->
+            Client.Pool.set_lldp_multicast_address ~rpc ~session_id ~self:pool
+              ~value:(Record_util.lldp_multicast_address_of_string v)
+          )
+          ()
       ; make_field ~name:"gui-config"
           ~get:(fun () -> get_from_map (x ()).API.pool_gui_config)
           ~add_to_map:(fun key value ->

ocaml/xapi/dbsync_master.ml

@@ -55,7 +55,8 @@ let create_pool_record ~__context =
       ~ext_auth_cache_size:50L ~ext_auth_cache_expiry:300L ~recommendations:[]
       ~license_server:[] ~ha_reboot_vm_on_internal_shutdown:true
       ~limit_console_sessions:false ~vm_console_idle_timeout:0L
-      ~auto_update_vm_secureboot_certificates:false
+      ~auto_update_vm_secureboot_certificates:false ~lldp_enabled:true
+      ~lldp_multicast_address:`nearestbridge
 
 let set_master_ip ~__context =
   let ip =