Edit

Managing Switch Policies

  • Article

Hyper-V extensible switch filtering and forwarding extensions can be provisioned with the properties of custom switch properties. Once provisioned, these extensions enforce the policies when they filter packets obtained on the extensible switch ingress data path. For more information about these policies, see Switch Policies.

The Hyper-V extensible switch interface uses the following object identifiers (OIDs) to provision filtering and forwarding extensions with the properties of custom switch policies:

OID_SWITCH_PROPERTY_ADD
This OID set request is issued by the protocol edge of the extensible switch to notify underlying extensions of the addition of a property at the WMI management layer. The InformationBuffer of the NDIS_OID_REQUEST structure contains a pointer to an NDIS_SWITCH_PROPERTY_PARAMETERS structure.

Note  Custom switch properties are specified by an NDIS_SWITCH_PROPERTY_TYPE enumeration value of NdisSwitchPropertyTypeCustom.

OID_SWITCH_PROPERTY_UPDATE
This OID set request is issued by the protocol edge of the extensible switch to notify underlying extensions of the update of a property at the WMI management layer. The InformationBuffer of the NDIS_OID_REQUEST structure contains a pointer to an NDIS_SWITCH_PROPERTY_PARAMETERS structure.

OID_SWITCH_PROPERTY_DELETE
This OID set request is issued by the protocol edge of the extensible switch to notify underlying extensions of the deletion of a property at the WMI management layer. The InformationBuffer of the NDIS_OID_REQUEST structure contains a pointer to an NDIS_SWITCH_PROPERTY_DELETE_PARAMETERS structure.

OID_SWITCH_PROPERTY_ENUM
This OID method request is sent by the extension to query the underlying miniport edge of the extensible switch about the currently configured switch properties on the extensible switch. The InformationBuffer of the NDIS_OID_REQUEST structure contains a pointer to a buffer. This buffer contains the following data:

Note  The extension must not originate OID set requests of OID_SWITCH_PROPERTY_ADD. OID_SWITCH_PROPERTY_UPDATE, or OID_SWITCH_PROPERTY_DELETE.

The extensible switch extension must follow these guidelines when it handles an OID set request of OID_SWITCH_PROPERTY_ADD, OID_SWITCH_PROPERTY_UPDATE, or OID_SWITCH_PROPERTY_DELETE:

  • The extension must not modify the NDIS_SWITCH_PROPERTY_PARAMETERS or NDIS_SWITCH_PROPERTY_DELETE_PARAMETERS structure that is associated with the OID request.

  • The extension must handle an OID_SWITCH_PROPERTY_UPDATE or OID_SWITCH_PROPERTY_DELETE set request if the extension has been previously provisioned with a switch property that matches the following members of the NDIS_SWITCH_PROPERTY_PARAMETERS or NDIS_SWITCH_PROPERTY_DELETE_PARAMETERS structure:

    • The PropertyType member that specifies the type of switch property.

      Note  Starting with NDIS 6.30, only switch properties of NdisSwitchPropertyTypeCustom are specified by the NDIS_SWITCH_PROPERTY_PARAMETERS or NDIS_SWITCH_PROPERTY_DELETE_PARAMETERS structures.

    • The PropertyId member that specifies a proprietary GUID value that the extension recognizes. This GUID value is created by the independent software vendor (ISV) who also defines the format of the custom extensible switch policy property.

      Note  A custom extensible switch policy property is contained within an NDIS_SWITCH_PROPERTY_CUSTOM structure.

  • If the extension handles these OID set requests, the extension must update or delete the switch policy that matches the following members of the NDIS_SWITCH_PROPERTY_PARAMETERS structure:

    • The PropertyVersion member that specifies the version of the extensible switch policy.

    • The PropertyInstanceId member that specifies the instance of the extensible switch policy.

    If the values of these members do not match a switch policy property for which the extension has been previously provisioned, the extension must fail the OID set request with NDIS_STATUS_INVALID_PARAMETER. Otherwise, the extension must complete the OID set request and return NDIS_STATUS_SUCCESS.

  • The filtering or forwarding extension can veto the addition, deletion, or update of a switch policy. The extension does this by completing the OID request with STATUS_DATA_NOT_ACCEPTED.

    Note  Capturing extensions must not veto the addition or update of a switch policy. Instead, it must forward the OID request down the extensible switch control path.

  • If the capturing or filtering extension successfully handles the OID set request for a custom switch policy, it must not complete the OID request and must forward it down the extensible switch control path.

    If the forwarding extension successfully handles the OID set request for a custom switch policy, it must complete the OID request and return the appropriate NDIS_STATUS_Xxx value.

  • If the extension does not complete the OID set request, it must call NdisFOidRequest to forward the OID request down the extensible switch driver stack. In this case, the extensions should monitor the completion status of the OID to detect whether an underlying extension has failed the OID request.