Summary

Configuration Manager introduced support for Office 365 agents in Current Branch 1602. There are no additional steps to perform when you configure Office 365 update deployments and in the way you configure Software Updates and Applications in Configuration Manager to use Nomad. However, the format of the content requests passed to Nomad differ considerably from all other types of content. This section describes how Office 365 types of deployments differ in terms of ACP requirements and goes on to describe how Nomad behaves during the download.

On this page

How it works

The Office 365 Click to Run agent (CTR) will process the update metadata obtained from the Configuration Manager Software Update Point and pass a request for content to the Configuration Manager agent. As with non-Office download requests, the same Alternate Content Provider API is used by the Configuration Manager agent; with the Configuration Manager agent Content Transfer Manager (CTM) thread invoking Nomad to download the requested content. When Nomad receives a download job with a manifest file from the CTM it will:

  1. Parse the manifest to retrieve the content description
  2. Download the content described in the manifest either from a DP or peer cache.
  3. Copy the downloaded data to the destination folder described in manifest.
  4. Notify Configuration Manager that the download job is complete.
  5. Wait for the next job.

For Office 365 updates the CTM passes different information to Nomad, when compared with other types of content download. The other types typically provide a content identifier i.e. Package ID and version. For Office 365 updates, a manifest file is also passed with the request. It is the manifest file that contains details of the content to be downloaded and its destination path (typically C:\ProgramData\Microsoft\ClickToRun\...). A single update may require multiple download jobs, resulting in multiple manifests being passed to Nomad while it is obtaining the content. Once the content has been downloaded, it is copied into the destination specified in the manifest file. Nomad does not configure hardlinks for Office 365 updates.

Hash checking and communication with the CTR agent

Another difference is that Office 365 updates do not have a Configuration Manager-generated hash associated with the content. For other types of content, Nomad performs an AES256 hash check prior to, and immediately after, download and compares this with the Configuration Manager hash in order to establish the content's validity. For Office 365 updates, there is no comparison hash made available to Nomad. Nomad therefore depends on the CTR for the validity status of the Office 365 update installation (the CTR performs its own hash check). Nomad also listens to the status API exposed by the CTR agent to check if the installation succeeded. If the installation fails, Nomad deletes the update from its cache and retries the download. As soon as Nomad receives a download success status, it sends a status message to the Nomad dashboard and stops listening to the CTR agent.

A bit about byte-ranges

In order to make the download process more efficient, Microsoft has implemented a process of byte-range requests rather than (or sometimes in addition to) requesting entire files. Nomad treats byte-range requests in just the same way as files and will initiate a local election for each to minimize the impact of any download across the WAN.

To process and download these byte-ranges, Nomad divides each Office365 package file into pages of 128MB, for example a 300MB file has 3 logical pages. If we think of a file as a book, then each page of the book is 128MB with each line of a page being 32KB. The byte-ranges described in the manifest indicates the start and end position within our lines of the page. Nomad normalises these byte-ranges to 32KB blocks, adjusting the start and end positions so that the byte-range contains complete lines and no line is truncated.

Nomad elections

Elections may occur when a Nomad agent requires content that is not resident in its cache. An election is not always necessary, with Nomad storing active download broadcast notifications in memory and then connecting direct to these hosts if itself requires the byte-range or file at some later time. All responses peers receive are stored in its Query Result Store (QRS). Before initiating an election, a Nomad agent will first verify its QRS to see if relevant peers are available for content downloads. If relevant peer(s) are found in the query store, an election does not occur.

When elections do occur and Nomad agents respond, the receiving agent sorts the list of responders top-down based upon the following criteria:

  • Longest byte-range on disk starting from requested offset
  • Longest relevant active downloader
  • Election weighting
  • NomadBranch service start-up time
  • Machine name

Under certain circumstances, an agent will not reply to an election request, even if it has the data in its cache. This happens when:

  • Request comes from an inhibited network
  • P2P SMB is disabled [Connectionless mode is not supported for Office 365 update deployments]
  • The Nomad Account (SMSNomadP2P&) is locked out
  • The Nomad Account (SMSNomadP2P&) is not active
  • The machine is a domain controller and SPECIALNETSHARE_MACHINEACCOUNT is not set in SpecialNetShare
  • The P2PElectionWeight registry value is set to zero
  • The Nomad share not available

Nomad Dashboard integration for Office 365

For all content deployment reporting, the Nomad Dashboard Operations panel relies on the following messages being returned by the Nomad agent:

  • SNO_EVT_REQUEST_STARTED
  • SNO_EVT_FINALSTATS
  • SNO_EVT_ERROR
  • SNO_EVT_REQUEST_COMPLETED

For non-Office downloads, the messages SNO_EVT_FINALSTATS and SNO_EVT_REQUEST_COMPLETED are sent upon completion of the deployment download job. Since Office updates deployments consist of multiple download jobs, Nomad will wait and listen for the CTR to indicate that it has successfully completed installation of the update before sending these messages to Configuration Manager. All other aspects of Nomad dashboard reporting are the same for Office update deployments.

Update download and installation example

We will start by installing an update that is not cached locally on one agent and therefore all download activity is from the distribution point. After that, we initiate an installation of the update on  the second agent and walk through the download from the first Nomad agent's cache.

  1. From Software Center, the Installation of the Office 365 update is initiated. During the download, its status is displayed at the bottom of the screen.
    Installing the Office 365 update from Software Center
  2. Browsing to the NomadBranch.log location (typically, located with Configuration Manager agent logs). When Nomad receives the download request (job) and manifest file from the Configuration Manager agent: 
    1. It checks its query results store (QRS) to see if any peer has broadcast that it is already downloading the content. 
    2. If the broadcast is not found, an election (network query) is initiated in an attempt to obtain the content from a peer. 
    3. If no peer responds, a download is initiated from a DP (4). 
    4. Once the download is complete, the data is copied into the location described in the manifest file.

    The log extract below shows all five events with the successful download (i641033.cab) from a DP. Office 365 downloads can be either a file or part of a file (byte-range). Our example illustrates a download for an entire file.
    Log extract for the download
  3.  The downloaded data is copied to the CTR location described in the manifest and is also retained in the Nomad cache. Our example illustrates the location of the Nomad cache with the file downloaded and a marker (full_file) to indicate that this is not a byte-range.
    The Nomad download cache
  4. For an Office 365 Update deployment, multiple jobs are passed to Nomad by the Configuration Manager agent. Once the downloaded job is completed, another BEGIN JOB appears in the log for the same update deployment. The same process is followed in the attempt to obtain the content locally. Our example illustrates a larger i640.cab file being downloaded.
    Downloading a file locally
    and the Nomad cache when the job completes.
    The Nomad download cache
  5. The third job to be passed to Nomad contains an instruction to download a byte-range for Stream.x86.x-none.dat.
    Download byte range
    An entry in the log describes the range (the byte-range is 268435456-268468224, a 32KB chunk that must reside in the second page file. Update files are broken down into 128MB page files.) and the subsequent election request attempting to locate it. 
  6. When the download completes and copied to the CTR location, more byte-range jobs related to the same file are logged.
    Additional bite-range jobs for the download
  7. Successive byte-range jobs are passed to the Nomad agent, downloaded into the cache and copied to the CTR location.
    Successive byte download jobs
    Once byte-range downloads are complete, Nomad copies them into the CTR update location at C:\ProgramData\Microsoft\ClickToRun\ProductReleases\<ProductCode>\<ProductCode>.<FileName>.tmp 
  8. It will be likely that hundreds of jobs are passed to Nomad for a single Office 365 update download. In our example, a total of 315 download jobs were requested by the Configuration Manager agent.
    The total of dowloaded files for the Office 365 update

  9. When a job completes, Nomad monitors the CTR agent interface to determine if actual update installation is successful. Once the CTR agent has all the files and byte-ranges that it needs, it merges the byte-ranges, performs a hash check on the contents and attempt to install the update.
    Installation status
    The status indicates Installing at this point and changes Installed when it is done.
  10. For an Office 365 Update download, you can verify the total amount of data downloaded from the DP by inspecting the registry. If you do not see a BytesFromPeer value, it means that all your downloads were from the DP.
    BytesfromPeer registry value
  11. Log on to the second Nomad agent and initiate the update installation from Software Center.
    The NomadBranch log file
    Browse to NomadBranch.log. The Standard P2P connecting to… and SMB Connected OK log entries indicates that it is initiating a download from the first agent. Initially, the agent registry does not display BytesFromDp as the second agent is able to obtain content from the first agent. 
    BytesFromDP registry value
    Due to differences in the state of the Office 365 installation on the second host, the CTR agent requested content that is not present on the first agent. Consequently, it  switches to download from the DP. Our example illustrates this event in the second agent's registry.
    Downloading from the DP
    When the download is complete, the values in the registry are updated.
    Updated registry when the download completes
  12. We can see the extent of the differences in the update installation on the two agents if we inspect the total downloads on the second agent; 467 downloads compared to 315 on the first agent.
    Differences in the update installation for the two agents

Which other Nomad features are supported by the Nomad Office 365 feature?

The following Nomad features are supported:

  • Peer copy over HTTP or HTTPS - from Nomad version 6.3 onwards, HTTPS can now be used to enable the Office 365 update byte-range request content to be shared amongst Nomad peers
  • Single-site download - from Nomad version 6.3 onwards, single-site download can now be used to locate byte-range request content across different subnets on the local branch. To support this feature Nomad requires ActiveEfficiency version 1.9.900. If you attempt to use the Office 365 updates feature with SSD and an earlier version of ActiveEfficiency it may still work but it will be less efficient. When this situation occurs a warning message will be output to the Nomad log file.
  • Peer-to-peer SMB – peers can download data from other peers using the SMB protocol
  • Work rates and cache priority – work rates determine the amount of bandwidth Nomad utilizes for the download and cache priority determines when the cache is purged
  • Download timeout – the timeout in seconds after which a job will be cancelled if the download has not been successful
  • Save and restore Nomad cache – custom task sequence action to save the Nomad cache either in WinPE or a full Microsoft Windows operating system and a custom task sequence action to restore the Nomad cache in the new Operating System during provisioning after Nomad has been installed
  • Deployment status messaging – status messaging for specific download events
  • Inhibited subnet and sites – defining subnets and AD sites where machines download from the DP and not participate in Nomad elections (status messages are not relayed)
  • SpecialNetShare – options for the Nomad share
  • Custom ports – enables the use of custom ports for data transfer and communications
  • Cache cleaning – enables cache management

The following are not supported by the Office 365 feature:

  • Cloud-based DP
  • Connectionless P2P
  • Multicast
  • Fanout
  • SMB downloads from the DP
  • Remote differential compression
  • Precaching
  • Hash or CRC validation
  • LSZ or metadata creation or download
  • SECure
  • Failover to BITS
  • Download from Microsoft Updates