Share via

3.1.1 Abstract Data Model

  • Article

This section describes a conceptual model of possible data organization that an implementation maintains to participate in this protocol. The described organization is provided to facilitate the explanation of how the protocol behaves. This document does not mandate that implementations adhere to this model as long as their external behavior is consistent with that described in this document.

Both the DSS and the USS maintain the following information regarding updates, target computers, target groups, and deployments.

Server Configuration: A set of configuration elements specified administratively for the server.

  • ServerID: A self-generated GUID that identifies the update server.

  • Replication Mode: Autonomous or replica, as specified in section 1.1.

  • CatalogOnlySync: A flag that indicates if the server stores the content files locally and exposes them as the USS content Download service. When set to FALSE, the server stores the content files locally and supports the USS content Download service. When set to TRUE, it specifies that the USS only supports the USS Web Services and does not support the USS content Download service.

  • LazySync: A flag that indicates when the content files are downloaded. This flag is ignored if CatalogOnlySync is set to TRUE. It can be one of the following:

    • TRUE: Content files are downloaded when the update is approved for install.

    • FALSE: Content files are downloaded when the update metadata is synchronized from a parent USS.

  • ServerHostsPsfFiles: A flag that indicates if the server will store the patch storage format (PSF) versions of content files if available for an update.

  • MaxNumberOfUpdatesPerRequest: The maximum number of revision IDs that the DSS is allowed to submit in the GetUpdateData (section 3.1.4.6) operation.

  • Languages Support: The list of languages known to the update server and a flag for each language indicating whether the update server supports the language.

  • All Languages: A flag indicating that the update server supports all languages. When All Languages is set to TRUE, the specific language settings MUST be ignored. If set to FALSE, the specific language settings define what languages are supported by the update server.

  • Specific Language Settings: Each supported language MUST include the following elements:

    • Language ID

    • Short name

    • Long name

    • Enabled state (TRUE/FALSE)

  • DoDetailedRollup: A flag that indicates if this update server allows DSSs to report detailed information about client computers that get updates from them.

    • TRUE: This update server allows DSSs to report detailed information about client computers that get updates from them.

    • FALSE: This update server does not allow DSSs to report detailed information about client computers that get updates from them as described in the RollupComputers, GetOutOfSyncComputers, and RollupComputerStatus methods.

Server State: A set of information about this server's runtime state.

  • ConfigAnchor: An anchor that identifies the last change in the configuration for the server.

Synchronization History Table: A table that tracks the completion time stamp of each successful synchronization with the USS. If this update server is configured as a replica server, a new entry MUST be added following the successful completion of the Deployments Synchronization (section 3.2.4.3) step. If this update server is configured as an Autonomous Server, a new entry MUST be added following the successful completion of the Metadata Synchronization (section 3.2.4.2) step. Existing entries in the table MAY be removed at any time. However, entries SHOULD NOT<11> be removed until they are at least 15 days old.

  • SynchronizationTime: A time stamp that identifies the time when this update server successfully completed the Deployments Synchronization (section 3.2.4.3) step if this server is a replica server, or completed the Metadata Synchronization (section 3.2.4.2) step if this server is an Autonomous Server.

Parent USS Configuration: Each update server has at most one parent USS. The following information on the parent USS is configured by an administrator and maintained by the update server:

  • Server FQDN or IP address where the USS Web Services is provided.

  • Server port on which the USS Web Services is provided.

Parent USS State: A set of information regarding the state of this server's communication with its USS. This information is received from the USS and is maintained for use within the protocol.

  • Last AuthorizationCookie received from the parent USS in a GetAuthorizationCookie (section 3.1.4.2) response.

  • Last Cookie received from the parent USS in a GetCookie (section 3.1.4.3) response.

  • Last ConfigAnchor received from the parent in a GetConfigData (section 3.1.4.4) response.

  • Last Sync anchor received from the parent USS in a GetRevisionIdList (section 3.1.4.5) response.

  • Last Deployment anchor received from the USS in a GetDeployments (section 3.1.4.10) response.

  • MaxNumberOfUpdatesPerRequest received from the parent USS in a GetConfigData (section 3.1.4.4) response.

  • List of languages supported by the USS. This is received from the parent USS in a GetConfigData (section 3.1.4.4) response.

  • CatalogOnlySync: A flag that indicates if the USS stores the content files locally. This is received from the parent USS in a GetConfigData (section 3.1.4.4).

  • LazySync: A flag that indicates when the content files are downloaded. This is received from the parent USS in a GetConfigData (section 3.1.4.4). This flag is ignored if CatalogOnlySync is set to TRUE. It can be one of the following:

    • TRUE: Download content when the update is approved for install.

    • FALSE: Download content immediately.

  • ServerHostsPsfFiles: Set to TRUE if the server stores the patch storage format (PSF) versions of content files when available; otherwise, set to FALSE. This is received from the parent USS in a GetConfigData (section 3.1.4.4).

TargetGroup Table: A table of entries that correspond to each target group that is configured on the update server. The entries in this table are administratively configured if the update server is an autonomous DSS of its parent USS. Otherwise, the entries in this table are received from the parent USS in response to invocations of the GetDeployments (section 3.1.4.10) method. Each entry is indexed by its TargetGroupID and MUST include the following elements:

  • TargetGroupID: A GUID that identifies this target group.

  • TargetGroupName: The name of the target group given as a string value.

  • IsBuiltin: A flag indicating whether this target group is provided by the implementation of the server or is created by a user.

  • ParentGroupID: Target groups can be nested. The ParentGroupID is the GUID of another target group from this table that is the parent of this target group in the nesting hierarchy.

DSS Table: A table that stores the information about each DSS and descendant DSSs that synchronize with this update of this update server.

A new entry is added to this table when a GetAuthorizationCookie message is received for the first time from a DSS. New entries are also added to this table when the USS receives a RollupDownstreamServers message that contains information on new DSSs. Existing entries can be modified or removed at any time. When an entry is deleted from this table, all entries in the client computers table with a ParentServerID value matching the ServerID value of the deleted entry MUST be deleted.<12>

Each entry is keyed by the ServerID and MUST include the following elements:

  • ServerID: The GUID that identifies this DSS.

  • FQDN of the DSS.

  • ParentServerID: The ServerID of the USS that this DSS synchronizes with.

  • LastRollupTime: A time stamp that indicates the time when this DSS last reported information on itself to its USS by calling the RollupDownstreamServers method. The value MUST be initialized to NULL.

  • LastSyncTime: A time stamp that identifies when this DSS last synchronized with its parent USS. The value MUST be initialized to NULL.

  • Version: The version number of the software on the DSS that gives it the capability to synchronize with the USS.<13>

  • IsReplica: A flag indicating whether this DSS is configured to be an Autonomous DSS or a Replica DSS of its parent USS.

  • UpdateCount: The number of updates known to the DSS.

  • DeclinedUpdateCount: The number updates that have been marked as hidden on the DSS.

  • ApprovedUpdateCount: The number of updates that have at least one Deployment with an Action of Install or Uninstall on the DSS.

  • NotApprovedUpdateCount: The number of updates that are not marked as hidden and have no Deployments with an Action of Install or Uninstall on the DSS.

  • UpdatesWithStaleUpdateApprovalsCount: The number of updates that have at least one Deployment with an Action of Install or Uninstall on the DSS where the deployment is associated with a revision of the update other than the latest revision.

  • ExpiredUpdateCount: The number of updates on the DSS that are no longer useful and do not have any deployments.

  • CriticalOrSecurityUpdatesNotApprovedForInstallCount: The number of updates that are related to the security of the client computers or are otherwise considered critical that have no Deployments with an Action of Install on the DSS.

  • WsusInfrastructureUpdatesNotApprovedForInstallCount: The number of updates that the client computers installs to enable them to continue to get updates from the DSS, which have no Deployments with an Action of Install on the DSS.

  • UpdatesWithClientErrorsCount: The number of updates on the DSS that at least one client computer has attempted and failed to install.

  • UpdatesWithServerErrorsCount: The number of updates on the DSS for which the DSS has attempted to download content but was unable to complete the download due to an error.

  • UpdatesNeedingFilesCount: The number of updates on the DSS for which the DSS downloads content but has not completed the download.

  • UpdatesNeededByComputersCount: The number of updates on the DSS that have at least one client computer that it is applicable to but not yet installed on.

  • UpdatesUpToDateCount: The number updates on the DSS that are known to be installed on all client computers that it is applicable to.

  • CustomComputerTargetGroupCount: The number of target groups on the DSS that have been created administratively on the DSS or have been received from its USS.

  • ComputerTargetCount: The number of client computers that get updates from this DSS.

  • ComputerTargetsNeedingUpdatesCount: The number of client computers that get updates from this DSS, on which at least one update is known to be applicable, but not yet installed.

  • ComputerTargetsWithUpdateErrorsCount: The number of client computers that get updates from this DSS that has tried and failed to install at least one update.

  • ComputersUpToDateCount: The number of client computers that get updates from this DSS that are known to have successfully installed all updates that are applicable to it.

Client computers table: A table that stores the information on each client computer that gets updates from this update server or from a descendant DSS. New entries are added to this table on the USS when a DSS reports information on new client computers to the USS using the RollupComputers method. New entries can be added to this table when new client computers are discovered through other implementation-specific means. Existing entries MAY be modified or removed at any time.<14>

Each entry is indexed by the ComputerID and MUST include the following elements:

  • ComputerID: A globally unique string that identifies this client computer.

  • ParentServerID: The ServerID of the update server that the client computer gets updates from.

  • LastSyncTime: A time stamp that identifies when this client computer last contacted the update server to get updates. The value MUST be initialized to NULL.

  • LastSyncResult: The result of the last attempt by this client computer to get updates from the update server. The valid values are the following:

    • Unknown/not applicable: The result is unknown, or the client computer has never attempted to get updates from the update server.

    • Succeeded: The client computer successfully retrieved updates from the update server.

    • Failed: The client computer failed to retrieve updates from the update server.

  • LastSentStatusRollupNumber: The RollupNumber value that was used when this update server last sent information about this client computer to the USS using the RollupComputerStatus method.

  • LastReceivedStatusRollupNumber: The RollupNumber value that was used when this update server last received information about this client computer from a DSS.

  • LastReportedRebootTime: A time stamp that identifies when this client computer notified the update server that it has rebooted. The value MUST be initialized to NULL.

  • LastInventoryTime: A time stamp indicating the last time this client computer reported software and hardware inventory information to the update server. The value MUST be initialized to NULL.

  • RequestedTargetGroupNames: A list of strings listing the target groups of which the client computer has been configured to be a member.

  • IPAddress: The IP address of the client computer.

  • FullDomainName: The FQDN of the client computer.

  • OSMajorVersion, OSMinorVersion, OSBuildNumber, OSServicePackMajorVersionNumber, OSServicePackMinorVersionNumber, OSLocale, SuiteMask, NewProductType, OldProductType, and SystemMetrics: These values are used to identify the operating system used by the client computer.

    This protocol provides a mechanism for transporting these values between update servers but does not specify how these values are initialized or how they are consumed. An implementation that consumes these values needs to have an out-of-band mechanism for determining their meaning.<15>

  • Computer manufacturer and model names.

  • Basic input/output system (BIOS) name, version, and release date.

  • Version number of the client software that gives the client computer the ability to get updates from the update server.

  • TargetGroupIDList: The list of GUIDs identifying the target groups that this client computer belongs to. Each GUID in the list corresponds to the TargetGroupID value from an entry in the TargetGroup Table.

  • HasDetailsChanged: A flag that indicates if the value of the RequestedTargetGroupNames, IPAddress, FullDomainName, operating system version number, computer manufacturer/model, BIOS name/version/release date, or the TargetGroupID element has changed since the last time information about this client computer was sent to the USS in a RollupComputers request. This value is set to TRUE when the value of one or more of these other elements is changed.

  • LastStatusRollupTime: A time stamp indicating when the status of updates on this client computer was last reported to the USS. The value MUST be initialized to NULL.

  • EffectiveLastDetectionTime: A time stamp indicating the time when the newest update that the client computer has reported status for was made available on the update server. This value MUST be initialized to NULL.

    This value is updated on the USS as part of the Reporting Data Synchronization step. If the implementation has the ability to receive messages from client computers describing the state of all updates on the client computer, then this field SHOULD<16> be updated at the same time these messages are processed.

Update Status Table: A table that tracks the status of each update on each client computer. Entries are added to, and removed from, this table on the USS when a DSS reports information regarding the status of updates on its client computers using the RollupComputerStatus method.

Entries MAY be added or removed through additional implementation-specific means.<17>

Each entry is indexed by the pair (ComputerID, UpdateID) and MUST include the following elements:

  • ComputerID: A globally unique string that identifies this client computer.

  • UpdateID: A GUID that identifies the update. This corresponds to the GUID portion of the UpdateIdentifier element in the Revision Table.

  • Status: The status of the update on the client computer. The valid values are shown in the following table.

    Value

    Meaning

    0

    The status of the update on the client computer is unknown.

    1

    The update is not applicable to the client computer (the software that the update is intended to update is not present).

    2

    The update is applicable to the client computer, but it has not yet been downloaded or installed.

    3

    The update is applicable to the client computer, and the client computer has downloaded all files required to install the update, but it has not installed the update yet.

    4

    The update is applicable to the client computer, and the update has been installed.

    5

    The update is applicable to the client computer, but the client computer either has failed to download the files required to install the update or has completed the download but has failed to install the update.

    6

    The update is applicable to the client computer, and the update has been installed, but the client computer is required to reboot before the update can take effect.

  • LastChangeTime: A time stamp indicating when the status of this update last changed on this client computer.

Client computer activity summary table: A table that tracks the number of times an update has been installed, successfully and unsuccessfully, by client computers. The client computers are grouped based on the update server that they get updates from, and the operating system used by the client computer. Entries are added, modified, and removed as part of the Reporting Data Synchronization step of this protocol.

Update server implementations MUST have the capability to receive notifications from client computers on which they have installed an update (or have failed to do so). The mechanism for receiving such notifications is implementation-dependent; however, when such notifications are received, this table SHOULD<18> be modified at that time as follows:

  1. Use the client computers table to determine the operating system version number of the client computer and the ServerID of the update server it gets updates from.

  2. Find the entry in this table with the corresponding operating system version number and ServerID. If no such entry exists, insert one.

  3. If the client computer has successfully installed an update, increment the InstallSuccessCount value of this entry. Otherwise, if the client computer failed to successfully complete the install, increment the InstallFailureCount value.

Each entry is indexed by the UpdateID, the ServerID, and the operating system version elements and MUST include the following elements:

  • UpdateID: A GUID that identifies the update. This corresponds to the GUID portion of the UpdateIdentifier element in the Revision Table.

  • ServerID: The ServerID of the update server that the client computers get updates from.

  • Operating system version: Consists of the OSMajorVersion, OSMinorVersion, OSBuildNumber, OSServicePackMajorVersionNumber, OSServicePackMinorVersionNumber, OSLocale, SuiteMask, NewProductType, OldProductType, and SystemMetrics values, corresponding to elements in the client computers table.

  • InstallSuccessCount: The number of times that client computers, running the operating system described by the operating system version elements, have successfully installed the update specified by the UpdateID element.

  • InstallFailureCount: The number of times that client computers, running the operating system described by the operating system version elements, have attempted unsuccessfully to install the update specified by the UpdateID element.

The InstallSuccessCount and InstallFailureCount values MUST be initialized to 0 and incremented accordingly whenever a client computer (using an operating system with version numbers matching the operating system version fields) notifies the update server that it has successfully or unsuccessfully installed this update. The mechanism used by client computers to notify the update server is implementation-dependent.<19>

The value is also modified, on both the USS and DSS, as part of the Reporting Data Synchronization (section 3.2.4.5) step of this protocol.

Categories Table: A table of entries corresponding to each category with which an update can be associated. Each entry is indexed by the CategoryIdentity and MUST include the following elements:

  • CategoryIdentity: This consists of a GUID that identifies the category and a revision number for each version of the category.

  • XMLMetaData: The metadata for the category.

  • LastChangedAnchor: An anchor that identifies when this entry was changed.

Update Classifications Table: A table of entries corresponding to each update classification that can be assigned to an update. The entries in this table are generated at runtime when this update server synchronizes its updates from its parent USS. Each entry is indexed/identified by the ClassificationIdentity and MUST include the following elements:

  • ClassificationIdentity: This consists of a GUID that identifies the update classification and a revision number for each version of the update classification.

  • XMLMetaData: The metadata for the update classification.

  • LastChangedAnchor: An anchor that identifies when this entry was changed.

Detectoids Table: A table of entries corresponding to each Detectoid. The entries in this table are generated at runtime when this update server synchronizes its updates from its parent USS. Each entry is indexed/identified by DetectoidIdentity and MUST include the following elements:

  • DetectoidIdentity: This consists of a GUID that identifies the Detectoid and a revision number for each version of the detectoid.

  • XMLMetaData: The metadata for the Detectoid.

  • LastChangedAnchor: An anchor that identifies when this entry was changed.

Revision Table: A table of entries corresponding to the revisions that exist for each update. The entries in this table are generated at runtime when this update server synchronizes its updates from its parent USS. Each entry is indexed/identified by UpdateIdentity and MUST include the following elements:

  • UpdateIdentity: This consists of a GUID that identifies the update and a revision number for each revision of the update.

  • XMLMetaData: The metadata for the update revision.

  • Hidden: A flag indicating if the administrator has chosen to hide this update. Hidden updates are assumed to be declined and will not be offered for deployment. When configured as a replica, a DSS gets information on hidden updates from its parent USS in the response to GetDeployments (section 3.1.4.10).

  • LastChangedAnchor: An anchor that identifies when this entry was changed.

  • Classification: An index into the update classification table identifying the update classification for this update revision.

  • For each content file associated with this revision:

    • FileDigest: An SHA-1 hash of the content file.

    • MUUrl: An HTTP URL specifying the location of this file on the Microsoft Update HTTP service. This field is NULL for updates that do not originate from the Microsoft Update website.

    • IsSecure: A bit field indicating whether the file uses a secure URL.<20>

    • IsEncrypted: A bit field indicating whether the file is encrypted.<21>

    • DecryptionKey: The key that is used to decrypt the file, if it is encrypted.<22>

    • If available, an AdditionalDigest element. The digest algorithm is specified by the Algorithm attribute. The digest value is specified as text within the AdditionalDigest element.<23>

EULAs Table: A table of entries corresponding to the End User License Agreement (EULA) for the software and driver update revisions. The entries in this table are populated at run time from the metadata associated with this revision using the EulaID property, as specified in section 3.1.1.1. The Accepted flag of each entry can be updated by administrative action. Each entry is uniquely identified by its EulaID and MUST include the following elements:

  • EulaID: This is a GUID that identifies the EULA.

  • Accepted: A flag indicating if this EULA was accepted by the administrator of this update server or its parent or ancestor update server.

Deployment Table: A table of entries corresponding to each deployment that is administratively approved for distribution to client computers and DSSs. The entries in this table are administratively configured if the update server is an autonomous DSS of its parent USS. Otherwise, the entries in this table are received from the parent USS using GetDeployments (section 3.1.4.10). Each entry is uniquely identified by DeploymentID and MUST include the following elements:

  • DeploymentID: This is a GUID that identifies the deployment.

  • UpdateIdentity: This consists of a GUID that identifies the update and a revision number for the update revision that is deployed by this deployment.

  • TargetGroupID: An index into the TargetGroup Table identifying the group of client computers to be targeted by this deployment.

  • Action: This field specifies the specific action defined by this deployment. The following are valid values for Action.

    Value

    Meaning

    0

    Install the update revision.

    1

    Uninstall the update revision.

    2

    Scan for the presence of the update revision.

    3

    Block.

  • AdminName: The login name of the administrator that created this deployment.

  • LastChangedAnchor: An anchor that identifies when this entry was changed.

  • All other deployment options as given in the ServerSyncDeployment structure specified in GetDeployments (section 3.1.4.10).

Content Store: A data store where content files are stored. The names of the files are as specified by the parent USS. The Content Store is empty if the CatalogOnlySync flag is set to FALSE for this update server. Each file is uniquely identified by the SHA-1 hash value. The Content Store stores the file by organizing them into folders with two character names that match the last two characters of the SHA-1 hash for files stored in that folder.