oxidecomputer · zeeshanlakhani · Nov 15, 2025 · Sep 25, 2025 · Aug 13, 2025 · Sep 29, 2025
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/common/src/address.rs b/common/src/address.rs
@@ -52,6 +52,55 @@ pub const IPV6_SSM_SUBNET: oxnet::Ipv6Net = oxnet::Ipv6Net::new_unchecked(
     12,
 );
 
+/// IPv4 multicast address range (224.0.0.0/4).
+/// See RFC 5771 (IPv4 Multicast Address Assignments):
+/// <https://www.rfc-editor.org/rfc/rfc5771>
+pub const IPV4_MULTICAST_RANGE: Ipv4Net =
+    Ipv4Net::new_unchecked(Ipv4Addr::new(224, 0, 0, 0), 4);
+
+/// IPv4 link-local multicast subnet (224.0.0.0/24).
+/// This range is reserved for local network control protocols and should not
+/// be routed beyond the local link. Includes addresses for protocols like
+/// OSPF (224.0.0.5), RIPv2 (224.0.0.9), and other local routing protocols.
+/// See RFC 5771 Section 4:
+/// <https://www.rfc-editor.org/rfc/rfc5771#section-4>
+pub const IPV4_LINK_LOCAL_MULTICAST_SUBNET: Ipv4Net =
+    Ipv4Net::new_unchecked(Ipv4Addr::new(224, 0, 0, 0), 24);
+
+/// IPv6 multicast address range (ff00::/8).
+/// See RFC 4291 (IPv6 Addressing Architecture):
+/// <https://www.rfc-editor.org/rfc/rfc4291>
+pub const IPV6_MULTICAST_RANGE: Ipv6Net =
+    Ipv6Net::new_unchecked(Ipv6Addr::new(0xff00, 0, 0, 0, 0, 0, 0, 0), 8);
+
+/// IPv6 multicast prefix (ff00::/8) mask/value for scope checking.
+pub const IPV6_MULTICAST_PREFIX: u16 = 0xff00;
+
+/// Admin-scoped IPv6 multicast prefix (ff04::/16) as u16 for address
+/// construction and normalization of underlay multicast addresses.
+pub const IPV6_ADMIN_SCOPED_MULTICAST_PREFIX: u16 = 0xff04;
+
+/// IPv6 interface-local multicast subnet (ff01::/16).
+/// These addresses are not routable and should not be added to IP pools.
+/// See RFC 4291 Section 2.7 (multicast scope field):
+/// <https://www.rfc-editor.org/rfc/rfc4291#section-2.7>
+pub const IPV6_INTERFACE_LOCAL_MULTICAST_SUBNET: oxnet::Ipv6Net =
+    oxnet::Ipv6Net::new_unchecked(
+        Ipv6Addr::new(0xff01, 0, 0, 0, 0, 0, 0, 0),
+        16,
+    );
+
+/// IPv6 link-local multicast subnet (ff02::/16).
+/// These addresses are not routable beyond the local link and should not be
+/// added to IP pools.
+/// See RFC 4291 Section 2.7 (multicast scope field):
+/// <https://www.rfc-editor.org/rfc/rfc4291#section-2.7>
+pub const IPV6_LINK_LOCAL_MULTICAST_SUBNET: oxnet::Ipv6Net =
+    oxnet::Ipv6Net::new_unchecked(
+        Ipv6Addr::new(0xff02, 0, 0, 0, 0, 0, 0, 0),
+        16,
+    );
+
 /// maximum possible value for a tcp or udp port
 pub const MAX_PORT: u16 = u16::MAX;
 

diff --git a/common/src/api/external/mod.rs b/common/src/api/external/mod.rs
@@ -957,6 +957,8 @@ pub enum ResourceType {
     LldpLinkConfig,
     LoopbackAddress,
     MetricProducer,
+    MulticastGroup,
+    MulticastGroupMember,
     NatEntry,
     Oximeter,
     PhysicalDisk,
@@ -2523,6 +2525,12 @@ impl Vni {
     /// The VNI for the builtin services VPC.
     pub const SERVICES_VNI: Self = Self(100);
 
+    /// VNI default if no VPC is provided for a multicast group.
+    ///
+    /// This is a low-numbered VNI to avoid colliding with user VNIs.
+    /// However, it is not in the Oxide-reserved range yet.
+    pub const DEFAULT_MULTICAST_VNI: Self = Self(77);
+
     /// Oxide reserves a slice of initial VNIs for its own use.
     pub const MIN_GUEST_VNI: u32 = 1024;
 

diff --git a/common/src/vlan.rs b/common/src/vlan.rs
@@ -16,7 +16,7 @@ pub const VLAN_MAX: u16 = 4094;
 
 /// Wrapper around a VLAN ID, ensuring it is valid.
 #[derive(Debug, PartialEq, Serialize, Deserialize, Clone, Copy, JsonSchema)]
-#[serde(rename = "VlanId")]
+#[serde(transparent)]
 pub struct VlanID(u16);
 
 impl VlanID {

diff --git a/dev-tools/omdb/tests/env.out b/dev-tools/omdb/tests/env.out
@@ -2,9 +2,9 @@ EXECUTING COMMAND: omdb ["db", "--db-url", "postgresql://root@[::1]:REDACTED_POR
 termination: Exited(0)
 ---------------------------------------------
 stdout:
- SERIAL                                    IP           ROLE      POLICY      STATE   ID                                   
- sim-..........<REDACTED_UUID>...........  [::1]:REDACTED_PORT  scrimlet  in service  active  ..........<REDACTED_UUID>........... 
- sim-..........<REDACTED_UUID>...........  [::1]:REDACTED_PORT  scrimlet  in service  active  ..........<REDACTED_UUID>........... 
+ SERIAL       IP           ROLE      POLICY      STATE   ID                                   
+ SimGimlet01  [::1]:REDACTED_PORT  scrimlet  in service  active  ..........<REDACTED_UUID>........... 
+ SimGimlet00  [::1]:REDACTED_PORT  scrimlet  in service  active  ..........<REDACTED_UUID>........... 
 ---------------------------------------------
 stderr:
 note: using database URL postgresql://root@[::1]:REDACTED_PORT/omicron?sslmode=disable
@@ -136,6 +136,11 @@ task: "metrics_producer_gc"
     unregisters Oximeter metrics producers that have not renewed their lease
 
 
+task: "multicast_reconciler"
+    reconciles multicast group and member state with dendrite switch
+    configuration
+
+
 task: "nat_garbage_collector"
     prunes soft-deleted NAT entries from nat_entry table based on a
     predetermined retention policy
@@ -364,6 +369,11 @@ task: "metrics_producer_gc"
     unregisters Oximeter metrics producers that have not renewed their lease
 
 
+task: "multicast_reconciler"
+    reconciles multicast group and member state with dendrite switch
+    configuration
+
+
 task: "nat_garbage_collector"
     prunes soft-deleted NAT entries from nat_entry table based on a
     predetermined retention policy
@@ -579,6 +589,11 @@ task: "metrics_producer_gc"
     unregisters Oximeter metrics producers that have not renewed their lease
 
 
+task: "multicast_reconciler"
+    reconciles multicast group and member state with dendrite switch
+    configuration
+
+
 task: "nat_garbage_collector"
     prunes soft-deleted NAT entries from nat_entry table based on a
     predetermined retention policy
@@ -683,9 +698,9 @@ EXECUTING COMMAND: omdb ["db", "sleds"]
 termination: Exited(0)
 ---------------------------------------------
 stdout:
- SERIAL                                    IP           ROLE      POLICY      STATE   ID                                   
- sim-..........<REDACTED_UUID>...........  [::1]:REDACTED_PORT  scrimlet  in service  active  ..........<REDACTED_UUID>........... 
- sim-..........<REDACTED_UUID>...........  [::1]:REDACTED_PORT  scrimlet  in service  active  ..........<REDACTED_UUID>........... 
+ SERIAL       IP           ROLE      POLICY      STATE   ID                                   
+ SimGimlet01  [::1]:REDACTED_PORT  scrimlet  in service  active  ..........<REDACTED_UUID>........... 
+ SimGimlet00  [::1]:REDACTED_PORT  scrimlet  in service  active  ..........<REDACTED_UUID>........... 
 ---------------------------------------------
 stderr:
 note: database URL not specified.  Will search DNS.
@@ -698,9 +713,9 @@ EXECUTING COMMAND: omdb ["--dns-server", "[::1]:REDACTED_PORT", "db", "sleds"]
 termination: Exited(0)
 ---------------------------------------------
 stdout:
- SERIAL                                    IP           ROLE      POLICY      STATE   ID                                   
- sim-..........<REDACTED_UUID>...........  [::1]:REDACTED_PORT  scrimlet  in service  active  ..........<REDACTED_UUID>........... 
- sim-..........<REDACTED_UUID>...........  [::1]:REDACTED_PORT  scrimlet  in service  active  ..........<REDACTED_UUID>........... 
+ SERIAL       IP           ROLE      POLICY      STATE   ID                                   
+ SimGimlet01  [::1]:REDACTED_PORT  scrimlet  in service  active  ..........<REDACTED_UUID>........... 
+ SimGimlet00  [::1]:REDACTED_PORT  scrimlet  in service  active  ..........<REDACTED_UUID>........... 
 ---------------------------------------------
 stderr:
 note: database URL not specified.  Will search DNS.

diff --git a/dev-tools/omdb/tests/successes.out b/dev-tools/omdb/tests/successes.out
@@ -89,9 +89,9 @@ EXECUTING COMMAND: omdb ["db", "sleds"]
 termination: Exited(0)
 ---------------------------------------------
 stdout:
- SERIAL                                    IP           ROLE      POLICY      STATE   ID                                   
- sim-..........<REDACTED_UUID>...........  [::1]:REDACTED_PORT  scrimlet  in service  active  ..........<REDACTED_UUID>........... 
- sim-..........<REDACTED_UUID>...........  [::1]:REDACTED_PORT  scrimlet  in service  active  ..........<REDACTED_UUID>........... 
+ SERIAL       IP           ROLE      POLICY      STATE   ID                                   
+ SimGimlet01  [::1]:REDACTED_PORT  scrimlet  in service  active  ..........<REDACTED_UUID>........... 
+ SimGimlet00  [::1]:REDACTED_PORT  scrimlet  in service  active  ..........<REDACTED_UUID>........... 
 ---------------------------------------------
 stderr:
 note: using database URL postgresql://root@[::1]:REDACTED_PORT/omicron?sslmode=disable
@@ -102,9 +102,9 @@ EXECUTING COMMAND: omdb ["db", "sleds", "-F", "discretionary"]
 termination: Exited(0)
 ---------------------------------------------
 stdout:
- SERIAL                                    IP           ROLE      POLICY      STATE   ID                                   
- sim-..........<REDACTED_UUID>...........  [::1]:REDACTED_PORT  scrimlet  in service  active  ..........<REDACTED_UUID>........... 
- sim-..........<REDACTED_UUID>...........  [::1]:REDACTED_PORT  scrimlet  in service  active  ..........<REDACTED_UUID>........... 
+ SERIAL       IP           ROLE      POLICY      STATE   ID                                   
+ SimGimlet01  [::1]:REDACTED_PORT  scrimlet  in service  active  ..........<REDACTED_UUID>........... 
+ SimGimlet00  [::1]:REDACTED_PORT  scrimlet  in service  active  ..........<REDACTED_UUID>........... 
 ---------------------------------------------
 stderr:
 note: using database URL postgresql://root@[::1]:REDACTED_PORT/omicron?sslmode=disable
@@ -371,6 +371,11 @@ task: "metrics_producer_gc"
     unregisters Oximeter metrics producers that have not renewed their lease
 
 
+task: "multicast_reconciler"
+    reconciles multicast group and member state with dendrite switch
+    configuration
+
+
 task: "nat_garbage_collector"
     prunes soft-deleted NAT entries from nat_entry table based on a
     predetermined retention policy
@@ -704,6 +709,12 @@ task: "metrics_producer_gc"
     started at <REDACTED_TIMESTAMP> (<REDACTED DURATION>s ago) and ran for <REDACTED DURATION>ms
 warning: unknown background task: "metrics_producer_gc" (don't know how to interpret details: Object {"expiration": String("<REDACTED_TIMESTAMP>"), "pruned": Array []})
 
+task: "multicast_reconciler"
+  configured period: every <REDACTED_DURATION>m
+  last completed activation: <REDACTED ITERATIONS>, triggered by <TRIGGERED_BY_REDACTED>
+    started at <REDACTED_TIMESTAMP> (<REDACTED DURATION>s ago) and ran for <REDACTED DURATION>ms
+warning: unknown background task: "multicast_reconciler" (don't know how to interpret details: Object {"disabled": Bool(false), "errors": Array [], "groups_created": Number(0), "groups_deleted": Number(0), "groups_verified": Number(0), "members_deleted": Number(0), "members_processed": Number(0)})
+
 task: "phantom_disks"
   configured period: every <REDACTED_DURATION>s
   last completed activation: <REDACTED ITERATIONS>, triggered by <TRIGGERED_BY_REDACTED>
@@ -1266,6 +1277,12 @@ task: "metrics_producer_gc"
     started at <REDACTED_TIMESTAMP> (<REDACTED DURATION>s ago) and ran for <REDACTED DURATION>ms
 warning: unknown background task: "metrics_producer_gc" (don't know how to interpret details: Object {"expiration": String("<REDACTED_TIMESTAMP>"), "pruned": Array []})
 
+task: "multicast_reconciler"
+  configured period: every <REDACTED_DURATION>m
+  last completed activation: <REDACTED ITERATIONS>, triggered by <TRIGGERED_BY_REDACTED>
+    started at <REDACTED_TIMESTAMP> (<REDACTED DURATION>s ago) and ran for <REDACTED DURATION>ms
+warning: unknown background task: "multicast_reconciler" (don't know how to interpret details: Object {"disabled": Bool(false), "errors": Array [], "groups_created": Number(0), "groups_deleted": Number(0), "groups_verified": Number(0), "members_deleted": Number(0), "members_processed": Number(0)})
+
 task: "phantom_disks"
   configured period: every <REDACTED_DURATION>s
   last completed activation: <REDACTED ITERATIONS>, triggered by <TRIGGERED_BY_REDACTED>
@@ -1851,30 +1868,30 @@ termination: Exited(0)
 ---------------------------------------------
 stdout:
 Installed RoT Bootloader Software
-BASEBOARD_ID                                        STAGE0_VERSION STAGE0_NEXT_VERSION 
-FAKE_SIM_SIDECAR:SimSidecar0                        unknown        unknown             
-FAKE_SIM_SIDECAR:SimSidecar1                        unknown        unknown             
-sim-gimlet:sim-..........<REDACTED_UUID>........... unknown        unknown             
-sim-gimlet:sim-..........<REDACTED_UUID>........... unknown        unknown             
+BASEBOARD_ID                 STAGE0_VERSION STAGE0_NEXT_VERSION 
+FAKE_SIM_SIDECAR:SimSidecar0 unknown        unknown             
+FAKE_SIM_SIDECAR:SimSidecar1 unknown        unknown             
+i86pc:SimGimlet00            unknown        unknown             
+i86pc:SimGimlet01            unknown        unknown             
 
 Installed RoT Software
-BASEBOARD_ID                                        SLOT_A_VERSION   SLOT_B_VERSION                
-FAKE_SIM_SIDECAR:SimSidecar0                        unknown (active) unknown                       
-FAKE_SIM_SIDECAR:SimSidecar1                        unknown (active) unknown                       
-sim-gimlet:sim-..........<REDACTED_UUID>........... unknown          unknown (ACTIVE SLOT UNKNOWN) 
-sim-gimlet:sim-..........<REDACTED_UUID>........... unknown          unknown (ACTIVE SLOT UNKNOWN) 
+BASEBOARD_ID                 SLOT_A_VERSION   SLOT_B_VERSION 
+FAKE_SIM_SIDECAR:SimSidecar0 unknown (active) unknown        
+FAKE_SIM_SIDECAR:SimSidecar1 unknown (active) unknown        
+i86pc:SimGimlet00            unknown (active) unknown        
+i86pc:SimGimlet01            unknown (active) unknown        
 
 Installed SP Software
-BASEBOARD_ID                                        SLOT0_VERSION SLOT1_VERSION 
-FAKE_SIM_SIDECAR:SimSidecar0                        unknown       unknown       
-FAKE_SIM_SIDECAR:SimSidecar1                        unknown       unknown       
-sim-gimlet:sim-..........<REDACTED_UUID>........... unknown       unknown       
-sim-gimlet:sim-..........<REDACTED_UUID>........... unknown       unknown       
+BASEBOARD_ID                 SLOT0_VERSION SLOT1_VERSION 
+FAKE_SIM_SIDECAR:SimSidecar0 unknown       unknown       
+FAKE_SIM_SIDECAR:SimSidecar1 unknown       unknown       
+i86pc:SimGimlet00            unknown       unknown       
+i86pc:SimGimlet01            unknown       unknown       
 
 Installed Host Phase 1 Software
-BASEBOARD_ID                                        SLED_ID                              SLOT_A_VERSION SLOT_B_VERSION                
-sim-gimlet:sim-..........<REDACTED_UUID>........... ..........<REDACTED_UUID>........... unknown        unknown (ACTIVE SLOT UNKNOWN) 
-sim-gimlet:sim-..........<REDACTED_UUID>........... ..........<REDACTED_UUID>........... unknown        unknown (ACTIVE SLOT UNKNOWN) 
+BASEBOARD_ID      SLED_ID                              SLOT_A_VERSION   SLOT_B_VERSION 
+i86pc:SimGimlet00 ..........<REDACTED_UUID>........... unknown (active) unknown        
+i86pc:SimGimlet01 ..........<REDACTED_UUID>........... unknown (active) unknown        
 
 Installed Host Phase 2 Software
 SLED_ID                              SLOT_A_VERSION      SLOT_B_VERSION 

diff --git a/end-to-end-tests/src/instance_launch.rs b/end-to-end-tests/src/instance_launch.rs
@@ -80,6 +80,7 @@ async fn instance_launch() -> Result<()> {
             auto_restart_policy: Default::default(),
             anti_affinity_groups: Vec::new(),
             cpu_platform: None,
+            multicast_groups: Vec::new(),
         })
         .send()
         .await?;

diff --git a/illumos-utils/src/opte/illumos.rs b/illumos-utils/src/opte/illumos.rs
@@ -52,6 +52,11 @@ pub enum Error {
     #[error("Tried to update external IPs on non-existent port ({0}, {1:?})")]
     ExternalIpUpdateMissingPort(uuid::Uuid, NetworkInterfaceKind),
 
+    #[error(
+        "Tried to update multicast groups on non-existent port ({0}, {1:?})"
+    )]
+    MulticastUpdateMissingPort(uuid::Uuid, NetworkInterfaceKind),
+
     #[error("Could not find Primary NIC")]
     NoPrimaryNic,
 

diff --git a/illumos-utils/src/opte/mod.rs b/illumos-utils/src/opte/mod.rs
@@ -31,6 +31,7 @@ use oxide_vpc::api::RouterTarget;
 pub use oxide_vpc::api::Vni;
 use oxnet::IpNet;
 pub use port::Port;
+pub use port_manager::MulticastGroupCfg;
 pub use port_manager::PortCreateParams;
 pub use port_manager::PortManager;
 pub use port_manager::PortTicket;
@@ -71,7 +72,7 @@ impl Gateway {
     }
 }
 
-/// Convert a nexus `IpNet` to an OPTE `IpCidr`.
+/// Convert a nexus [IpNet] to an OPTE [IpCidr].
 fn net_to_cidr(net: IpNet) -> IpCidr {
     match net {
         IpNet::V4(net) => IpCidr::Ip4(Ipv4Cidr::new(
@@ -85,9 +86,10 @@ fn net_to_cidr(net: IpNet) -> IpCidr {
     }
 }
 
-/// Convert a nexus `RouterTarget` to an OPTE `RouterTarget`.
+/// Convert a nexus [shared::RouterTarget] to an OPTE [RouterTarget].
 ///
-/// This is effectively a `From` impl, but defined for two out-of-crate types.
+/// This is effectively a [`From`] impl, but defined for two
+/// out-of-crate types.
 /// We map internet gateways that target the (single) "system" VPC IG to
 /// `InternetGateway(None)`. Everything else is mapped directly, translating IP
 /// address types as needed.

diff --git a/illumos-utils/src/opte/non_illumos.rs b/illumos-utils/src/opte/non_illumos.rs
@@ -46,6 +46,11 @@ pub enum Error {
     #[error("Tried to update external IPs on non-existent port ({0}, {1:?})")]
     ExternalIpUpdateMissingPort(uuid::Uuid, NetworkInterfaceKind),
 
+    #[error(
+        "Tried to update multicast groups on non-existent port ({0}, {1:?})"
+    )]
+    MulticastUpdateMissingPort(uuid::Uuid, NetworkInterfaceKind),
+
     #[error("Could not find Primary NIC")]
     NoPrimaryNic,