{"id":31643923,"url":"https://github.com/att/vfd","last_synced_at":"2025-10-07T04:07:39.646Z","repository":{"id":42651802,"uuid":"56247201","full_name":"att/vfd","owner":"att","description":null,"archived":false,"fork":false,"pushed_at":"2023-12-19T20:54:07.000Z","size":17971,"stargazers_count":74,"open_issues_count":16,"forks_count":36,"subscribers_count":34,"default_branch":"master","last_synced_at":"2024-03-15T04:38:33.116Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/att.png","metadata":{"files":{"readme":"README","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-04-14T15:06:26.000Z","updated_at":"2024-03-12T12:40:30.000Z","dependencies_parsed_at":"2022-09-14T17:01:51.897Z","dependency_job_id":null,"html_url":"https://github.com/att/vfd","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/att/vfd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/att%2Fvfd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/att%2Fvfd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/att%2Fvfd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/att%2Fvfd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/att","download_url":"https://codeload.github.com/att/vfd/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/att%2Fvfd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278717429,"owners_count":26033542,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-07T04:03:09.110Z","updated_at":"2025-10-07T04:07:39.637Z","avatar_url":"https://github.com/att.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"   \n\n\n\n  VFD OVERVIEW \n  Much  in  the  way  that  a guest operating system requires a \n  hypervisor to provide accessibility to  the  underlying  real \n  operating  system and hardware, as well as to ensure policies \n  are enforced, there is a similar need for  a  NIC  hypervisor \n  when  virtual  functions (VFs) are directly available through \n  SR-IOV[1]. While a bit more lightweight  than  a  hypervisor, \n  VFd  can  be  thought of as the NIC hypervisor inasmuch as it \n  provides the policy enforcement  through  both  configuration \n  and real-time validation of guest[2] requests. \n   \n  ![cannot display:\n  https://raw.githubusercontent.com/wiki/att/vfd/images/overview/overview.png \n  ](\n  https://raw.githubusercontent.com/wiki/att/vfd/images/overview/overview.png \n  ) \n  Figure 1: General relationship of NIC, VFs, \"guests\" and VFd \n   \n  Figure  1  illustrates the relationship between the NIC (PF), \n  the configured VFs, the guests, and  VFd.  VFd  acts  as  the \n  policy  implementor by configuring each VF to stipulate which \n  VLAN(s) a VF will receive traffic from,  and  be  allowed  to \n  send  traffic  to. In addition, VFd will configure the PF and \n  VFs to: \n   \n      \n      \n        \n          \n       * Strip and insert the outer VLAN tag. \n          \n       * Enable  NIC  bridging  allowing  guest  to  guest \n         communication. \n          \n       * Allow  unknown  unicast traffic to be sent to one \n         or more guests. \n          \n       * Allow  broadcast  and  multicast  traffic  to  be \n         received/transmitted by a guest. \n          \n       * Enforce  MAC  and/or  VLAN spoofing (drop spoofed \n         packets). \n          \n       * Configure multiple MAC addresses for the VF. \n          \n       * Enable and configure DCB quality of service. \n      \n      \n   \n   \n  In addition to  the  NIC  configurations  listed  above,  VFd \n  provides  the  means  to  access the packet and byte counters \n  allowing for them to be available to the user; something that \n  is not possible when using a kernel driver to manage the VFs. \n  Statistics, both at the PF and VF level include: \n   \n      \n      \n        \n          \n       * Packet counts for inbound (Rx) and outbound (Tx) \n          \n       * Byte counts, Tx and Rx \n          \n       * Error packet count \n          \n       * Count of spoofed packets \n      \n      \n   \n   \n\n  The Guests \n\n\n\n\n\n  While the illustration shows only one VF  allocated  to  each \n  guest,  it  is  possible  to  allocate  multiple  VFs,  from  \n  different PFs, to a single guest. Of the various guests shown \n  in  figure  1,  two  are illustrations of how guest operating \n  systems, virtual machines[3],  can  have  one,  or  more,  VF \n  allocated  as an SR-IOV device. Bare metal applications (e.g. \n  DPDK applications) are also able  to  make  use  of  the  VFs \n  offered  up  by the NIC and generally use the NIC's kernel VF \n  interface/driver to do so. \n\n  Inside of a VM \n\n\n\n\n\n  When a guest operating system is created, and one or more VFs \n  is  attached  to  it,  the  VF  appears  as a virtual network \n  interface and standard kernel drivers can be  used  to  treat \n  the  interface  as  an ordinary ethernet device, configurable \n  with well known tools like ifconfig and ip, or a DPDK  driver \n  may  be used to allow DPDK applications to run in the virtual \n  machine. \n\n  What VFd Is Not \n\n\n\n\n\n  While VFd is implemented as a DPDK application, primarily  to \n  easily  access  the  network  devices,  VFd  is  not a packet \n  processor, and does not insert itself into the  path  of  any \n  packet. \n\n\n\n  NECESSITY \n  A  valid,  and  often  asked,  question is why exactly is VFd \n  needed? It would seem that if the hardware offers all of  the \n  sophistication  that  they  do, that the kernel drivers would \n  supply the means to configure the hardware such that  all  of \n  the  features could be used. However, at least at the present \n  time,   this   isn't   the   case,  and  there  are  several  \n  configuration  options which unfortunately cannot be achieved \n  through the kernel drivers. In order to take  full  advantage \n  of  the  hardware, an independent configuration tool, VFd, is \n  required. \n   \n\n  Real-time Authorisation \n\n\n\n\n\n  In addition to managing the configurations of  all  VFs,  VFd \n  also provides real-time policy enforcement when a guest makes \n  a request to configure  it's  interface.  The  following  are \n  examples  of  guest actions which require the approval of VFd \n  before the requested changes are actually applied o the VF: \n   \n   \n      \n        \n     * Add or modify VLAN ID(s) \n        \n     * Change default MAC address \n        \n     * Add/delete alternate (white list) MAC addresses \n        \n     * Set the MTU value \n   \n   \n   \n  VFd will authorise (ACK) any request provided that the change \n  is  within  the  policy  as  defined to VFd via the PF and VF \n  configuration files. For example, if  a  guests  requests  to \n  add/modify  a  VLAN  ID,  it  will  be  permitted only if the \n  requested ID has been defined in the VF's configuration file. \n  MTU  changes  are  limited by the overall maximum MTU defined \n  for each device in the main VFd configuration  file.  Looking \n  from a policy assurance point of view, VFd provides a service \n  that would  otherwise  not  be  available  even  if  all  NIC \n  features  could  be  exercised  through  the  kernel  driver  \n  interface as the drivers provide no mechanism to call out  to \n  an independent authority to make these kinds of decisions. \n   \n\n\n\n  VF CONFIGURATION FEATURES \n  The  following  sections  provide a high level explanation of \n  NIC features which may be managed using VFd. The purpose here \n  is  to  outline  what  can be done; for information on how to \n  actually implement these, please  refer  to  the  VFd  User's \n  Guide. \n\n  Anti-Spoofing \n\n\n\n\n\n  Spoofing  is  used  in  reference  to  a machine on a network \n  pretending to be another machine, usually by using the  other \n  machine's  MAC  address,  or using an unauthorised VLAN ID in \n  packets, or possibly both. VFd forces anti-spoofing  settings \n  to  be  enabled  for  VLAN IDs[4] under the assumption that a \n  guest assigned to a VLAN must always send  packets  with  the \n  assigned ID, but may send with any source MAC address. \n\n  VLAN Considerations \n\n\n\n\n\n  The  list  of  approved  VLAN  IDs  that  are given in a VF's \n  configuration file  limit  the  packets  that  the  NIC  will \n  forward  to  the  VF. Only packets containing one of the VLAN \n  IDs in the list are allowed to pass. VFd does not permit a VF \n  to  see all packets regardless of VLAN ID, nor does it permit \n  untagged packets from being written onto a VF's queue. \n   \n  ![cannot display:\n  https://raw.githubusercontent.com/wiki/att/vfd/images/overview/vlan_strip.png \n  ](\n  https://raw.githubusercontent.com/wiki/att/vfd/images/overview/vlan_strip.png \n  ) \n  Figure 2: On transmit, insert VLAN tag into  untagged  packet \n  (top  to  middle), and into a single tagged packet (middle to \n  bottom). On receipt, the reverse. \n   \n\n  Stripping and Inserting VLAN Tags \n  The VLAN ID, or tag, may be automatically removed,  stripped, \n  as  a packet is received, and automatically inserted prior to \n  transmission; both of these actions are performed by the  NIC \n  and  thus are as efficient as is possible. Whether or not one \n  or multiple VLAN IDs are configured for a VF,  the  stripping \n  of  the  tag is straight forward: the tag is removed from the \n  packet before the packet is presented to the VF. For the case \n  where  a  VF  receives  packets  with  a single VLAN tag, the \n  process of  insertion  is  also  straight  forward:  the  NIC \n  inserts  the  tag into the packet before transmission. When a \n  VF is permitted send and receive packets using one of several \n  VLAN   IDs,   the   insertion  of  the  correct  ID  is  the  \n  responsibility of the sending process, and cannot be added to \n  the packet by the NIC. \n\n  Q in Q Stripping \n  Packets  arriving  with multiple embedded VLAN IDs (figure 2, \n  bottom), also known as Q  in  Q,  are  subject  to  the  same \n  stripping  practice  as  described  above. Only the first, or \n  outer tag, is removed from a received packet,  and  only  the \n  outer   tag   will   be  inserted  on  transmit.  Using  the  \n  illustration as  an  example,  the  middle  packet  would  be \n  delivered to the guest after stripping, and the bottom packet \n  would be transmitted. It is the responsibility of  the  guest \n  software  (kernel  driver,  or  DPDK application) to properly \n  distinguish packets, if necessary, based on the VLAN ID which \n  remains in the packet. \n\n  MAC Addresses \n\n\n\n\n\n  By default the NIC generates a random MAC address for each VF \n  that is created. This random address is known as the  default \n  MAC,  and  is  visible to the guest (e.g. it is what would be \n  displayed in the output of an ifconfig  command).  If  it  is \n  necessary,  the default MAC address can be supplied in a VF's \n  configuration file which  will  replace  the  random  address \n  generated by the NIC. \n\n  Guest Generated MAC Addresses \n  It is sometimes desirable for a guest to generate the default \n  MAC, and possibly other white-list MAC  addresses.  VFd  will \n  approve these guest requests provided that: \n      \n      \n        \n          \n       * The  address  is  not in use by another VF on the \n         same PF. \n          \n       * The number of addresses  currently  allocated  on \n         the VF is not at maximum \n          \n       * THe  number  of  addresses currently allocated on \n         the PF is not at maximum. \n      \n      \n   \n   \n  Guest allocated MAC addresses remain in place  until  the  VF \n  configuration  is  deleted. When the configuration is deleted \n  any guest allocated  addresses  are  replaced  by  a  single, \n  randomly generated, default address. \n\n  Broadcast, Unknown Unicast, Multicast Traffic \n\n\n\n\n\n  VFd allows each VF to be configured to cause the NIC to allow \n  or reject each of these types of traffic.  The  configuration \n  of a VF provides for three independent settings allowing each \n  to be managed separately. All  packets  falling  within  each \n  traffic  type  are  subject  to  VLAN  filtering;  it  is not \n  possible for a VF to see all *-cast traffic. \n\n\n\n  PF CONFIGURATION FEATURES \n  There are several configuration  options  that  VFd  provides \n  which  apply  to all VFs on a given NIC, or to all PFs on the \n  NIC, and thus are supplied  in  the  main  VFd  configuration \n  file.  These  configuration  options  are  described  in  the \n  following sections. \n\n  Loopback \n\n\n\n\n\n  By default the NIC bridge is disabled which forces  a  packet \n  to  be  transmitted  to the switch, and then back, should two \n  guests using VFs on the same PF need to communicate. Enabling \n  the  loopback  option for a VF will enable the NIC bridge and \n  allow packets to be exchanged between VFs on the  PF  without \n  having to travel onto the real network. \n\n  Flow Control \n\n\n\n\n\n  While   evidence   suggests  that  using  flow  control  can  \n  significantly impact performance (max throughput),  VFd  does \n  allow flow control on the NIC to be enabled. \n\n  Quality of Service \n\n\n\n\n\n  VFd  is  able  to  configure  all  PFs  to  enable Datacenter \n  Bridging (DCB) quality of service.  This  defines  a  set  of \n  traffic classes and allows the assignment of bandwidth shares \n  (percentages) for each VF with respect to each traffic class. \n\n  MTU Limit \n\n\n\n\n\n  The overall maximum MTU limit can be set  on  each  PF.  When \n  set,  an  attempt  by  a guest to increase the MTU value over \n  this limit will be rejected. \n\n\n\n  TRAFFIC MIRRORING \n  Traffic mirroring is a  specialised  form  of  loopback.  VFd \n  provides  for  real-time mirror configuration, independent of \n  VF configuration files, allowing for inbound[5], outbound, or \n  all  of a VF's traffic to be duplicated and passed to another \n  VF on the same PF. \n   \n   \n  ![cannot display:\n  https://raw.githubusercontent.com/wiki/att/vfd/images/overview/mirror_in.png \n  ](\n  https://raw.githubusercontent.com/wiki/att/vfd/images/overview/mirror_in.png \n  ) \n  Figure 3:  Inbound  mirroring  showting  traffic  also  being \n  delivered to Guest B. \n   \n  ![cannot display:\n  https://raw.githubusercontent.com/wiki/att/vfd/images/overview/mirror_out.png \n  ](\n  https://raw.githubusercontent.com/wiki/att/vfd/images/overview/mirror_out.png \n  ) \n  Figure  4:  Outbound  mirroring  showing  all Tx traffic from \n  Guest A delivered to Guest B. \n   \n   \n   \n  Mirroring  traffic  locally  has  benefits  with  respect  to \n  debugging  connectivity issues as well as application issues. \n  However, there are potential impacts, some  serious,  to  the \n  overall  throughput  of the NIC when traffic is mirrored over \n  the NIC bridge. For instance,  a  badly  behaved  application \n  used  as  the receiver for mirrored traffic has the potential \n  to block all traffic to the source VF. \n\n\n\n  NOTES \n   \n  _____________________________________________________________\n     \n    [1] A basic primer on SR-IOV can be found via the following \n    URL: \n    www.intel.com/content/dam/doc/application-note/pci-sig-sr-iov-primer-sr-iov-technology-paper.pdf \n     \n   \n   \n     \n    [2] For the purposes of this document, we use the term \n    guest to mean either a guest operating system or any \n    application which has been given direct access to an SR-IOV \n    device. \n     \n   \n   \n     \n    [3] To avoid confusion, we tend not to use the acronym VM \n    when refering to a guest operating system (virtual machine) \n    as some vendors refer to the virtual functions on the NIC \n    as VMs which could lead to confusion. \n     \n   \n   \n     \n    [4] For some NICs in order to enable VLAN anti-spoofing, \n    MAC anti-spoofing must also be enabled. \n     \n   \n   \n     \n    [5] The directional notation of mirrored traffic is \n    relative to the guest, and not to the NIC or switch. Thus \n    inbound means traffic received; inbound to the guest. \n     \n   \n  _____________________________________________________________\n   \n   \n   \n   \n   \n   \n  _____________________________________________________________\n   \n      \n             \n     Source vfd/doc/overview/overview.xfm \n             \n     Original   \n            19 February 2018 \n             \n     Revised   \n            2 March 2018 \n             \n     Formatter   \n            tfm V2.2/0a266 \n      \n   \n   \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatt%2Fvfd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fatt%2Fvfd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatt%2Fvfd/lists"}