Document link: https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/configuring_and_managing_virtualization/index

Section number and name: Section 14.7, Managing SR-IOV Devices. Or Section 17; Configuring virtual machine network connections

Describe the issue: We need documentation for how MAC Addresses work. The existing documentation may also need an update to use modern predictable NIC names on the host.

Impact of this issue: Nobody knows how to set up VM MAC Addresses using SR-IOV. So it's a random crapshoot making it work. This creates customer frustration, which generates extra support cases, which consumes extra time from support teams, which costs Red Hat time, money, and customer goodwill.

Suggestions for improvement: Either update section 14.7 or add a new section 17.3.4, titled, SR-IOV. At minimum, include this text. 

************************

If you want a permanent MAC Address and stable network configuration for your VM using an SR-IOV Virtual Function (VF), then use the virsh edit or virsh attach-device command to assign the VF in an <interface type='hostdev'> block of your virtual machine XML file, like this.

<interface type='hostdev'>
  ...
  <mac address='52:54:00:00:01:01'/>
  //(optional if you want to specify your own MAC Address)
  ...
</interface>

If you don't specify a MAC Address, then libvirt on the host will generate and maintain a permanent, pseudo-random MAC address beginning with OUI "52:54:00." Either way, the guest will always see a permanent MAC address, so its network configuration will be stable.

You may also assign an SR-IOV VF to a virtual machine by adding a device entry in the <hostdev> section of your virtual machine XML file. But unlike regular network devices, SR-IOV VF network devices configured this way acquire new MAC addresses with each host reboot. Because of this, the guest will believe it found new hardware, and the guest will usually need to re-configure its network settings. This behavior is usually undesirable.