How CAU Plug-ins Work

Tip

In the CAU UI, you can only specify a single plug-in for CAU to use to preview or to apply updates during an Updating Run. By using the CAU Windows PowerShell cmdlets, you can specify one or more plug-ins. If you need to install multiple types of updates on the cluster, it is usually more efficient to specify multiple plug-ins in one Updating Run, rather than using a separate Updating Run for each plug-in. For example, fewer node restarts will typically occur.

In the CAU UI, you select a plug-in from a drop-down list of available plug-ins when you use CAU to perform the following actions:

• Apply updates to the cluster
  
  
• Preview updates for the cluster
  
  
• Configure cluster self-updating options
  
  

By default, CAU selects the plug-in Microsoft.WindowsUpdatePlugin. However, you can specify any plug-in that is installed and registered with CAU.

By using the CAU Windows PowerShell cmdlets that are listed in the following table, you can specify one or more plug-ins for an Updating Run or scan by passing the –CauPluginName parameter. You can specify multiple plug-in names by separating them with commas. If you specify multiple plug-ins, you can also control how the plug-ins influence each other during an Updating Run by specifying the -RunPluginsSerially, -StopOnPluginFailure, and –SeparateReboots parameters. For more information about using multiple plug-ins, use the links provided to the cmdlet documentation in the following table.

If you do not specify a CAU plug-in parameter by using these cmdlets, the default is the plug-in Microsoft.WindowsUpdatePlugin.

When you configure the Updating Run options, you can specify one or more name=value pairs (arguments) for the selected plug-in to use. For example, in the CAU UI, you can specify multiple arguments as follows:

Name1=Value1;Name2=Value2;Name3=Value3

These name=value pairs must be meaningful to the plug-in that you specify. For some plug-ins the arguments are optional.

The syntax of the CAU plug-in arguments follows these general rules:

• Multiple name=value pairs are separated by semicolons.
  
  
• A value that contains spaces is surrounded by quotation marks, for example: Name1="Value with Spaces".
  
  
• The exact syntax of value depends on the plug-in.
  
  

To specify plug-in arguments by using the CAU Windows PowerShell cmdlets that support the –CauPluginParameters parameter, pass a parameter of the form:

-CauPluginArguments @{Name1=Value1;Name2=Value2;Name3=Value3}

You can also use a predefined Windows PowerShell hash table. To specify plug-in arguments for more than one plug-in, pass multiple hash tables of arguments, separated with commas. Pass the plug-in arguments in the plug-in order that is specified in CauPluginName.

The plug-ins that CAU installs (Microsoft.WindowsUpdatePlugin and Microsoft.HotfixPlugin) provide additional options that you can select. In the CAU UI, these appear on an Additional Options page after you configure Updating Run options for the plug-in. If you are using the CAU Windows PowerShell cmdlets, these options are configured as optional plug-in arguments. For more information, see Use the Microsoft.WindowsUpdatePlugin and Use the Microsoft.HotfixPlugin later in this topic.

You can configure a plug-in argument for the default plug-in, Microsoft.WindowsUpdatePlugin, that consists of a Windows Update Agent (WUA) query string. This instruction uses the WUA API to identify one or more groups of Microsoft updates to apply to each node, based on specific selection criteria. You can combine multiple criteria by using a logical AND or a logical OR. The WUA query string is specified in a plug-in argument as follows:

QueryString="Criterion1=Value1 and/or Criterion2=Value2 and/or…”

For example, Microsoft.WindowsUpdatePlugin automatically selects important updates by using a default QueryString argument that is constructed using the IsInstalled, Type, IsHidden, and IsAssigned criteria:

QueryString="IsInstalled=0 and Type='Software' and IsHidden=0 and IsAssigned=1"

If you specify a QueryString argument, it is used in place of the default QueryString that is configured for the plug-in.

Example 1

To configure a QueryString argument that installs a specific update as identified by ID f6ce46c1-971c-43f9-a2aa-783df125f003:

QueryString="UpdateID='f6ce46c1-971c-43f9-a2aa-783df125f003' and IsInstalled=0"

Note

The preceding example is valid for applying updates by using the Cluster-Aware Updating Wizard. If you want to install a specific update by configuring self-updating options with the CAU UI or by using the Add-CauClusterRole or Set-CauClusterRole Windows PowerShell cmdlet, you must format the UpdateID value with two single-quote characters: QueryString="UpdateID=''f6ce46c1-971c-43f9-a2aa-783df125f003'' and IsInstalled=0"

Example 2

To configure a QueryString argument that installs only drivers:

QueryString="IsInstalled=0 and Type='Driver' and IsHidden=0"

For more information about query strings for the default plug-in, Microsoft.WindowsUpdatePlugin, the search criteria (such as IsInstalled), and the syntax that you can include in the query strings, see the section about search criteria in the Windows Update Agent (WUA) API Reference.

For the hotfix plug-in to work, hotfixes must be stored in a well-defined structure in an SMB file share (hotfix root folder), and you must configure the hotfix plug-in with the path to the hotfix root folder by using the CAU UI or the CAU Windows PowerShell cmdlets. This path is passed to the plug-in as the HotfixRootFolderPath argument. You can choose one of several structures for the hotfix root folder, according to your updating needs, as shown in the following examples. Files or folders that do not adhere to the structure are ignored.

Example 1. Folder structure used to apply hotfixes to all cluster nodes

To specify that hotfixes apply to all cluster nodes, copy them to a folder named CAUHotfix_All under the hotfix root folder. In this example, the HotfixRootFolderPath plug-in argument is set to \\MyFileServer\Hotfixes\Root\. The CAUHotfix_All folder contains three updates with the extensions .msu, .msi, and .msp that will be applied to all cluster nodes. The update file names are only for illustration purposes.

Note
In this and the following examples, the hotfix configuration file with its default name DefaultHotfixConfig.xml is shown in its required location in the hotfix root folder.

\\MyFileServer\Hotfixes\Root\ 
   DefaultHotfixConfig.xml
   CAUHotfix_All\ 
      Update1.msu 
      Update2.msi 
      Update3.msp
      ...

Example 2. Folder structure used to apply certain updates only to a specific node

To specify hotfixes that apply only to a specific node, use a subfolder under the hotfix root folder with the name of the node. Use the NetBIOS name of the cluster node, for example, ContosoNode1. Then, move the updates that apply only to this node to this subfolder. In the following example, the HotfixRootFolderPath plug-in argument is set to \\MyFileServer\Hotfixes\Root\. Updates in the CAUHotfix_All folder will be applied to all cluster nodes, and Node1_Specific_Update.msu will be applied only to ContosoNode1.

\\MyFileServer\Hotfixes\Root\ 
   DefaultHotfixConfig.xml
   CAUHotfix_All\ 
      Update1.msu 
      Update2.msi 
      Update3.msp
      ...
   ContosoNode1\ 
      Node1_Specific_Update.msu 
      ... 

Example 3. Folder structure used to apply updates other than .msu, .msi, and .msp files

By default, Microsoft.HotfixPlugin only applies updates with the .msu, .msi, or .msp extension. However, certain updates might have different extensions and require different installation commands. For example, you might need to apply a firmware update with the extension .exe to a node in a cluster. You can configure the hotfix root folder with a subfolder that indicates a specific, non-default update type should be installed. You must also configure a corresponding folder installation rule that specifies the installation command in the <FolderRules> element in the hotfix configuration XML file.

In the following example, the HotfixRootFolderPath plug-in argument is set to \\MyFileServer\Hotfixes\Root\. Several updates will be applied to all cluster nodes, and a firmware update SpecialHotfix1.exe will be applied to ContosoNode1 by using FolderRule1. For information about configuring FolderRule1 in the hotfix configuration file, see Customize the hotfix configuration file later in this topic.

\\MyFileServer\Hotfixes\Root\ 
   DefaultHotfixConfig.xml
   CAUHotfix_All\ 
      Update1.msu 
      Update2.msi 
      Update3.msp
      ...

   ContosoNode1\ 
      FolderRule1\
          SpecialHotfix1.exe
      ... 

The hotfix configuration file controls how Microsoft.HotfixPlugin installs specific hotfix file types in a failover cluster. The XML schema for the configuration file is defined in HotfixConfigSchema.xsd, which is located in the following folder on a computer where the CAU tools are installed:

%systemroot%\System32\WindowsPowerShell\v1.0\Modules\ClusterAwareUpdating folder

To customize the hotfix configuration file, copy the sample configuration file DefaultHotfixConfig.xml from this location to the hotfix root folder and make appropriate modifications for your scenario.

Important
To apply most hotfixes provided by Microsoft and other updates, the default hotfix configuration file can be used without modification. Customization of the hotfix configuration file is a task only in advanced usage scenarios.

By default, the hotfix configuration XML file defines installation rules and exit conditions for the following two categories of hotfixes:

• Hotfix files with extensions that the plug-in can install by default (.msu, .msi, and .msp files).
  
  These are defined as <ExtensionRules> elements in the <DefaultRules> element. There is one <Extension> element for each of the default supported file types. The general XML structure is as follows:
  
  
  XML

  Copy

  <DefaultRules>
      <ExtensionRules>
        <Extension name="MSI">
          <!-- Template and ExitConditions elements for installation of .msi files follow -->
           ...
        </Extension>
        <Extension name="MSU">
          <!-- Template and ExitConditions elements for installation of .msu files follow -->
           ...
        </Extension>
        <Extension name="MSP">
          <!-- Template and ExitConditions elements for installation of .msp files follow -->
           ...
        </Extension>
           ...
     </ExtensionRules>
  </DefaultRules>
  
  

  If you need to apply certain update types to all cluster nodes in your environment, you can define additional <Extension> elements.
  
  
• Hotfix or other update files that are not .msi, .msu, or .msp files, for example, non-Microsoft drivers, firmware, and BIOS updates.
  
  Each non-default file type is configured as a <Folder> element in the <FolderRules> element. The name attribute of the <Folder> element must be identical to the name of a folder in the hotfix root folder that will contain updates of the corresponding type. The folder can be in the CAUHotfix_All folder or in a node-specific folder. For example, if FolderRule1 is configured in the hotfix root folder, configure the following element in the XML file to define an installation template and exit conditions for the updates in that folder:
  
  
  XML

  Copy

  <FolderRules>
        <Folder name="FolderRule1">
          <!-- Template and ExitConditions elements for installation of updates in FolderRule1 follow -->
           ...
        </Folder>
        ...
  </FolderRules>
  
  

The following tables describe the <Template> attributes and the possible <ExitConditions> subelements.

<ExitConditions> subelement	Description
<Success>	Defines one or more exit codes that indicate the specified update succeeded. This is a required subelement.
<Success_RebootRequired>	Optionally defines one or more exit codes that indicate the specified update succeeded and the node must restart. Note Optionally, the <Folder> element can contain the alwaysReboot attribute. If this attribute is set, it indicates that if a hotfix installed by this rule returns one of the exit codes that is defined in <Success>, it is interpreted as a <Success_RebootRequired> exit condition.
<Fail_RebootRequired>	Optionally defines one or more exit codes that indicate the specified update failed and the node must restart.
<AlreadyInstalled>	Optionally defines one or more exit codes that indicate the specified update was not applied because it is already installed.
<NotApplicable>	Optionally defines one or more exit codes that indicate the specified update was not applied because it does not apply to the cluster node.

Important
Any exit code that is not explicitly defined in <ExitConditions> is interpreted as the update failed, and the node does not restart.

You must perform several steps to configure the SMB file server and file share to help secure the hotfix root folder files and hofix configuration file for access only in the context of Microsoft.HotfixPlugin. These steps enable several features that help prevent possible tampering with the hotfix files in a way that might compromise the failover cluster.

The general steps are as follows:

1. Identify the user account that is used for Updating Runs by using the plug-in
   
   
2. Configure this user account in the necessary groups on an SMB file server
   
   
3. Configure permissions to access the hotfix root folder
   
   
4. Configure settings for SMB data integrity
   
   
5. Enable a Windows Firewall rule on the SMB server
   
   

Step 1. Identify the user account that is used for Updating Runs by using the hotfix plug-in

The account that is used in CAU to check security settings while performing an Updating Run using Microsoft.HotfixPlugin depends on whether CAU is used in remote-updating mode or self-updating mode, as follows:

• Remote-updating mode   The account that has administrative privileges on the cluster to preview and apply updates.
  
  
• Self-updating mode   The name of the virtual computer object that is configured in Active Directory for the CAU clustered role. This is either the name of a prestaged virtual computer object in Active Directory for the CAU clustered role or the name that is generated by CAU for the clustered role. To obtain the name if it is generated by CAU, run the Get-CauClusterRole CAU Windows PowerShell cmdlet. In the output, ResourceGroupName is the name of the generated virtual computer object account.
  
  

Step 2. Configure this user account in the necessary groups on an SMB file server

Important
You must add the account that is used for Updating Runs as a local administrator account on the SMB server. If this is not permitted because of the security policies in your organization, configure this account with the necessary permissions on the SMB server by using the following procedure.

Step 3. Configure permissions to access the hotfix root folder

By default, when you attempt to apply updates, the hotfix plug-in checks the configuration of the NTFS file system permissions for access to the hotfix root folder. If the folder access permissions are not configured properly, an Updating Run using the hotfix plug-in might fail.

If you use the default configuration of the hotfix plug-in, ensure that the folder access permissions meet the following requirements.

• The Users group has Read permission.
  
  
• If the plug-in will apply updates with the .exe extension, the Users group has Execute permission.
  
  
• Only certain security principals are permitted (but are not required) to have Write or Modify permission. The allowed principals are the local Administrators group, SYSTEM, CREATOR OWNER, and TrustedInstaller. Other accounts or groups are not permitted to have Write or Modify permission on the hotfix root folder.
  
  

Optionally, you can disable the preceding checks that the plug-in performs by default. You can do this in one of two ways:

• If you are using the CAU Windows PowerShell cmdlets, configure the DisableAclChecks='True' argument in the CauPluginArguments parameter for the hotfix plug-in.
  
  
• If you are using the CAU UI, select the Disable check for administrator access to the hotfix root folder and configuration file option on the Additional Update Options page of the wizard that is used to configure Updating Run options.
  
  

However, as a best practice in many environments, we recommend that you use the default configuration to enforce these checks.

Step 4. Configure settings for SMB data integrity

To check for data integrity in the connections between the cluster nodes and the SMB file share, the hotfix plug-in requires that you enable settings on the SMB file share for SMB signing or SMB Encryption. SMB Encryption, which provides enhanced security and better performance in many environments, is supported starting in Windows Server 2012. You can enable either or both of these settings, as follows:

• To enable SMB signing, see the procedure in the article 887429 in the Microsoft Knowledge Base.
  
  
• To enable SMB Encryption for the SMB shared folder, run the following Windows PowerShell cmdlet on the SMB server:
  
  
  Copy

  Set-SmbShare <ShareName> -EncryptData $true
  
  

  Where <ShareName> is the name of the SMB shared folder.
  
  

Optionally, to enforce the use of SMB Encryption in the connections to the SMB server, select the Require SMB Encryption in accessing the hotfix root folder option in the CAU UI, or configure the RequireSMBEncryption='True' plug-in argument by using the CAU Windows PowerShell cmdlets.

Important
If you select the option to enforce the use of SMB Encryption, and the hotfix root folder is not configured for connections that use SMB Encryption, the Updating Run will fail.

Step 5. Enable a Windows Firewall rule on the SMB server

You must enable the File Server Remote Management (SMB-in) rule in Windows Firewall on the SMB file server. This is enabled by default in Windows Server 2012 R2 and Windows Server 2012.