RPS Patch Manifest Definition

Last updated on August 11, 2021.

Document Status: Document Feature Complete as of August 11, 2021; PENDING EXTERNAL REVIEW.

This document describes the patch manifest of the Rapid Provisioning System (RPS).

Note

The word "package" is used instead of "patch" within the manifest XML to maintain backwards compatibility with RPS v3.1.

Users may see "patch" and "package" used interchangeably in the code and log outputs during this process.

What is the Patch Manifest File

When creating the ZIP file that houses all the data needed to install a patch, there also needs to be a patch manifest file created with the patch. It is used by RPS to apply the patches and to determine what targets are to receive the patches.

The manifest file lives at the root level of the ZIP archive and is named Package.RPS. It contains information such as the Operating System (OS) Type, OS Architecture, patch name, etc.

Important

Patch names must begin with a letter to be valid. They cannot start with a number or special character.

Structure of the Patch Manifest File

The internal structure of the patch manifest file is JSON with XML, containing a predetermined set of elements. The values contained in these elements will be the details applied to the patch and used to transfer, apply, and manage the patches on an RPS enabled system.

Important

Any XML element that has a String field must have the first letter of "String" capitalized for this field to be valid. Example: <String>Windows 10</String>

<?xml version="1.0" encoding="utf-8"?>
<PackageManifest version="1.0">
  <Architecture></Architecture>
  <Conditions>
    <PackageAssignmentCondition>
        <Property />
        <Operator />
        <Value />
    </PackageAssignmentCondition>
  </Conditions>
  <DependsOn />
  <Description></Description>
  <InstallArguments />
  <InstallerFileName></InstallerFileName>
  <Miscellaneous />
  <MsCatalogId />
  <MsCatalogLinkUrls />
  <MsCatalogProductName></MsCatalogProductName>
  <MsCatalogSupercededByKbIds />
  <MsCatalogTitle />
  <MsCatalogUpdateId />
  <OsType></OsType>
  <OsVersion></OsVersion>
  <PackageClassification></PackageClassification>
  <PackageName></PackageName>
  <PackageVersion></PackageVersion>
  <ProductId></ProductId>
  <ProductName></ProductName>
  <ProductType></ProductType>
  <ProductVersion></ProductVersion>
  <Products />
  <Supersedes>
    <String>PackageName/PackageVersion</String>
  </Supersedes>
  <SuppressReboot></SuppressReboot>
  <UninstallArguments></UninstallArguments>
</PackageManifest>

Patch Manifest XML Attributes

Version Attribute

Type: String

IsRequired: Yes

The version of the patch manager that will process this manifest file.

Currently, the following version(s) exist:

<PatchManifest version="1.0">

Patch Manifest XML Elements

Architecture Element

Type: String

IsRequired: Yes

The architecture of the operating system to whom the patch is applicable. A wildcard (*) can be passed in to target any OS version. Acceptable values are:

Note

The patch will only be assigned to targets that have an Architecture value that passes the match test on this element, in addition to the OsType and OsVersion values.

Conditions Element

Type: Collection of PackageAssignmentCondition

IsRequired: No

A collection of custom conditions for filtering patch assignments to a target.

<Conditions>
    <PackageAssignmentCondition>
      <Property>IsApp</Property>
      <Operator>Eq</Operator>
      <Value>True</Value>
    </PackageAssignmentCondition>
  </Conditions>

Important

The fields inside the PackageAssignmentCondition must be in the following order to be valid:

<Property></Property>
<Operator></Operator>
<Value></Value>

Known Issue

Patch manifest Conditions element Value field does not support multiple values separated by the pipe delimiter |

Error Details: The following PackageManifest code snippet is an example using pipe delimiter | in Conditions, which will fail:
```
<InstallerFileName>opera.msi</InstallerFileName>
<Conditions>
  <PackageAssignmentCondition>
    <Property>Name</Property>
    <Operator>Eq</Operator>
    <Value>ad.unit.domain|nosc.local.rps</Value>
  </PackageAssignmentCondition>
</Conditions>
```
The resulting behavior: Only the first value listed in the Value field will receive an assignment; all other values after the pipe delimiter | are ignored.

Figure 1: Pipe delimiter error example.

In the above example, ad.unit.domain is assigned the opera patch, because it was listed before the pipe delimiter | . nosc.local.rps is not assigned the opera patch, because it was listed after the pipe delimiter | .
Current Workaround for pipe delimiter | : Utilize the Match Operator field <Operator>Match</Operator>, with each value in the Value field wrapped in parentheses () and with a trailing question mark ? . Example:
```
<Conditions>
    <PackageAssignmentCondition>
        <Property>ComputerName</Property>
        <Operator>Match</Operator>
        <Value>(NFA)?(WNM)?(WNMA)?</Value>
    </PackageAssignmentCondition>
</Conditions>
```
In the above example, a target with a Property of ComputerName will be assigned if its Value contains NFA, WNM, and/or WNMA. This implementation only requires a partial value match.

For an exact value match, the full string in the Value field must be enclosed with a caret ^ and a dollar sign $ . Example:
```
<Conditions>
    <PackageAssignmentCondition>
        <Property>ComputerName</Property>
        <Operator>Match</Operator>
        <Value>^(NFA)?(WNM)?(WNMA)?$</Value>
    </PackageAssignmentCondition>
</Conditions>
```
In the above example, a target with a Property of ComputerName will be assigned if its Value contains NFA, WNM, and WNMA.

DependsOn Element

Type: Collection of Strings

IsRequired: No

A collection of products a patch depends on. The value is in the format of ProductName/ProductVersion.

<DependsOn>
    <String>Patch1/1.0.0</String>
    <String>Patch2/1.5.2</String>
</DependsOn>

Description Element

Type: String

IsRequired: No

A description of the patch and what it is installing.

InstallArguments Element

Type: String

IsRequired: No

Arguments passed in when executing the InstallerFileName in order to install the patch.

InstallerFileName Element

Type: String

IsRequired: Yes

The name of the file inside of the patch ZIP archive that should be executed to begin the install/uninstall process. This file must live at the root of the patch.

Miscellaneous Element

Type: Collection of Strings

IsRequired: No

Allows extra information to be stored in a patch manifest. Any child element(s) can be added to the Miscellaneous element.

<Miscellaneous>
  <CreatedByUser>myUserName</CreatedByUser>
  <CreatedOnDate>4/21/2020 12:00:00 PM</CreatedOnDate>
</Miscellaneous>

MsCatalogId Element

Type: String

IsRequired: No

The catalog ID of the patch. Used/Populated by updates that come from the Microsoft Catalog.

MsCatalogLinkUrls Element

Type: Collection of Strings

IsRequired: No

The catalog link URLs for the patch. Used/Populated by updates that come from the Microsoft Catalog.

<MsCatalogLinkUrls>
    <String>https://www.catalog.update.microsoft.com/ScopedViewInline.aspx?updateid=db57861b-e22b-4107-8c78-1ae8d63310d2</String>
    <String>https://www.catalog.update.microsoft.com/ScopedViewInline.aspx?updateid=567d7a0d-7f11-4c75-ba80-e7dd1b88fbe3</String>
    <String>https://www.catalog.update.microsoft.com/ScopedViewInline.aspx?updateid=5f46c0b9-c57c-484e-b6e5-80dded34bfa3</String>
</MsCatalogLinkUrls>

MsCatalogProductName Element

Type: String

IsRequired: No

The catalog product name of the patch. Used/Populated by updates that come from the Microsoft Catalog.

MsCatalogSupercededByKbIds Element

Type: Collection of Strings

IsRequired: No

The catalog IDs of KBs that supersede the patch. Used/Populated by updates that come from the Microsoft Catalog.

<MsCatalogSupercededByKbIds>
    <String>4532693</String>
    <String>4532695</String>
    <String>4528760</String>
</MsCatalogSupercededByKbIds>

MsCatalogTitle Element

Type: String

IsRequired: No

The catalog title of the patch. Used/Populated by updates that come from the Microsoft Catalog.

MsCatalogUpdateId Element

Type: String

IsRequired: No

The catalog update ID of the patch. Used/Populated by updates that come from the Microsoft Catalog.

OsType Element

Type: String

IsRequired: Yes

The type of the operating system. The supported values are:

Windows
Linux

Note

The patch will only be assigned to targets that have an OsType value that passes the match test on this element, in addition to the Architecture and OsVersion values.

OsVersion Element

Type: String

IsRequired: Yes

The version of the operating system to whom the patch is applicable. A wildcard (*) can be passed in to target any OS version. Partial wildcard matching is also allowed, which means it will match the values before and after the wildcard.

For example:

10.* would match 10.0.0.2, 10.2, etc., because they all start with "10.".
*.1 would match 10.0.1, 10.1, etc because they all end with ".1".

Note

The patch will only be assigned to targets who have an OsVersion value that passes the match test on this element, in addition to the Architecture and OsType values.

PackageClassification Element

Type: String

IsRequired: Yes

The classification of the patch. Accepted values are:

Critical
Definition
General
New
Script
Security

PackageName Element

Type: String

IsRequired: Yes

The name of the patch to be used by RPS. This name is used in combination with the PackageVersion element to create a unique name.

PackageVersion Element

Type: String

IsRequired: Yes

The version of the patch to be used by RPS. This name is used in combination with the PackageName element to create a unique name. The value stored in here typically follows Semantic Versioning (e.g., 1.0.0).

ProductId Element

Type: String

IsRequired: Yes, if ProductType is WindowsCabinet, WindowsExe, WindowsHotfix, WindowsMsi, or WindowsMsp.

The ID of the product. Used when registering the product with the OS, if needed.

ProductName Element

Type: String

IsRequired: Yes, if ProductType is WindowsExe, WindowsMsi, or WindowsMsp.

The name of the product. Used when registering the product with the OS, if needed.

ProductType Element

Type: String

IsRequired: Yes

The type of product. Determines the type of patch being installed.

Acceptable values are:

LinuxRpm
ScriptFramework
WindowsCabinet
WindowsExe
WindowsHotfix
WindowsMsi
WindowsMsp

ProductVersion Element

Type: String

IsRequired: Yes, if ProductType is WindowsExe, WindowsMsi, or WindowsMsp.

The Version of the product. Used when registering the patch with the OS, if needed.

Products Element

Type: Collection of Strings

IsRequired: No

A collection of products a patch affects/supports. For example, a Windows update might patch Windows 10 and Visual Studio.

<Products>
    <String>Windows 10</String>
    <String>Visual Studio</String>
</Products>

Supersedes Element

Type: Collection of Strings

IsRequired: No

A collection of products a patch supersedes. The value is in the format of ProductName/ProductVersion.

<Supersedes>
    <String>Patch1/1.0.0</String>
    <String>Patch2/1.5.2</String>
</Supersedes>

SuppressReboot Element

Type: Boolean (True/False)

IsRequired: Yes

Determines whether or not the machine should reboot after installing/uninstalling the patch.

If True, the machine should not reboot. If False, the machine should reboot.

UninstallArguments Element

Type: String

IsRequired: No

Arguments passed in when executing the InstallerFileName in order to uninstall the patch.

PackageManifest Examples

3^rd Party Application Patch Manifest

Example of a manifest used to install Firefox to a Windows machine:

<?xml version="1.0" encoding="utf-8"?>
<PackageManifest version="1.0">
  <Architecture>x64</Architecture>
  <Description>This will install Firefox v70 on all Windows x64 bit machines</Description>
  <InstallArguments />
  <InstallerFileName>firefox.msi</InstallerFileName>
  <MsCatalogId />
  <MsCatalogLinkUrls />
  <MsCatalogProductName>Firefox70</MsCatalogProductName>
  <MsCatalogSupercededByKbIds />
  <MsCatalogTitle />
  <MsCatalogUpdateId />
  <OsType>Windows</OsType>
  <OsVersion>*</OsVersion>
  <PackageClassification>General</PackageClassification>
  <PackageName>Firefox</PackageName>
  <PackageVersion>1.0.0</PackageVersion>
  <ProductId>{74994757-3b19-4c54-afe4-ae84e398a3f7}</ProductId>
  <ProductName>Mozilla Firefox 70.0 (x64 en-US)</ProductName>
  <ProductType>WindowsMsi</ProductType>
  <ProductVersion>70.0</ProductVersion>
  <Products />
  <Supersedes>
    <String>Firefox/0.9.0</String>
  </Supersedes>
  <SuppressReboot>true</SuppressReboot>
  <UninstallArguments>/s</UninstallArguments>
</PackageManifest>

Linux Software Patch Manifest

Example of a manifest used to install Socat to a Linux machine:

<?xml version="1.0" encoding="utf-8"?>
<PackageManifest version="1.0">
  <Architecture>x64</Architecture>
  <Description>This contains the install for Socat</Description>
  <InstallArguments />
  <InstallerFileName>socat-1.7.3.2-2.el7.x86_64.rpm</InstallerFileName>
  <OsType>Linux</OsType>
  <OsVersion>*</OsVersion>
  <PackageClassification>General</PackageClassification>
  <PackageName>socat</PackageName>
  <PackageVersion>1.7.3.2</PackageVersion>
  <ProductId>socat</ProductId>
  <ProductName>socat</ProductName>
  <ProductType>LinuxRpm</ProductType>
  <ProductVersion>1.7.3.2</ProductVersion>
  <Products />
  <UninstallArguments>/s</UninstallArguments>
  <SuppressReboot>true</SuppressReboot>
</PackageManifest>

Appliance Patch Manifest

Example of a manifest used to update an ESX environment:

<?xml version="1.0" encoding="utf-8"?>
<PackageManifest version="1.0">
  <Architecture>x64</Architecture>
  <Description>This is a test patch</Description>
  <InstallArguments />
  <InstallerFileName>windows8.1-kb4519990-x64.msu</InstallerFileName>
  <MsCatalogId />
  <MsCatalogLinkUrls />
  <MsCatalogSupercededByKbIds />
  <MsCatalogProductName>kb4519990</MsCatalogProductName>
  <MsCatalogTitle />
  <MsCatalogUpdateId />
  <OsType>Windows</OsType>
  <OsVersion>*</OsVersion>
  <PackageClassification>General</PackageClassification>
  <PackageName>windows8.1-kb4519990-x64</PackageName>
  <PackageVersion>2019.10.8</PackageVersion>
  <ProductId>kb4519990</ProductId>
  <ProductName>windows8.1-kb4519990-x64</ProductName>
  <ProductType>WindowsHotfix</ProductType>
  <ProductVersion>2019.10.8</ProductVersion>
  <Products />
  <SuppressReboot>false</SuppressReboot>
  <UninstallArguments>/s</UninstallArguments>
</PackageManifest>

Get-RpsPatchManifest

The cmdlet Get-RpsPatchManifest will return the XML schema for the patch manifest file. The cmdlet takes one optional parameter: Version.

Version: Optional. Used to specify a patch manifest version to validate against. If this parameter is not provided, this cmdlet will return the most current version of the manifest schema.

Note
Currently the only valid value for Version is 1.0 .

$currentSchema = Get-RpsPatchManifest

Test-RpsPatchManifest

The cmdlet Test-RpsPatchManifest will take the path to a patch manifest file and validate the file XML format. The cmdlet takes two parameters: PatchFilePath and, optionally, SchemaVersion.

PatchFilePath: Required. Provides the path to the patch manifest file to be validated.
SchemaVersion: Optional. Used to specify a patch manifest version to validate against. If this parameter is not provided, the latest version of the manifest schema will be used to perform the validation.

Note
Currently the only valid value for SchemaVersion is 1.0 .

If the manifest is valid, Test-RpsPatchManifest will return true. If the manifest is invalid, Test-RpsPatchManifest will return false, with a list of validation exceptions.

$result = Test-RpsPatchManifest -PatchFilePath C:\patch\manifest.xml

RPS Patch Manifest Definition

Note

What is the Patch Manifest File

Important

Structure of the Patch Manifest File

Important

Patch Manifest XML Attributes

Version Attribute

Patch Manifest XML Elements

Architecture Element

Note

Conditions Element

Important

Known Issue

DependsOn Element

Description Element

InstallArguments Element

InstallerFileName Element

Miscellaneous Element

MsCatalogId Element

MsCatalogLinkUrls Element

MsCatalogProductName Element

MsCatalogSupercededByKbIds Element

MsCatalogTitle Element

MsCatalogUpdateId Element

OsType Element

Note

OsVersion Element

Note

PackageClassification Element

PackageName Element

PackageVersion Element

ProductId Element

ProductName Element

ProductType Element

ProductVersion Element

Products Element

Supersedes Element

SuppressReboot Element

UninstallArguments Element

PackageManifest Examples

3rd Party Application Patch Manifest

Linux Software Patch Manifest

Appliance Patch Manifest

Get-RpsPatchManifest

Note

Test-RpsPatchManifest

Note

3^rd Party Application Patch Manifest