Depot Sync 4.0 Getting Started
Getting Started with Depot Topology and Tag-Based Package Sync
Table of Contents
Overview
Depot Sync 4.0 controls how your depots receive objects (Software Packages) and how they connect to each other. Instead of maintaining individual depot server settings and Agent Templates per depot, you now manage this centrally in the Empirum Management Console (EMC) through a Depot Topology, Connection Profiles, and Tags.
This article covers site management with the Depot Topology, selective Tag-based package synchronization, the initial setup, the migration from Depot Sync 3.x, and troubleshooting.
What's New
Compared to the previous depot management, Depot Sync 4.0 introduces four changes:
- Depot Topology: Shows centrally how your depots are connected to each other.
- Connection Profiles: Define how assigned depots reach a depot or the Master Server.
- Tags: Optionally control which objects are synchronized to which depot. In this release, Tags apply to Software Packages only.
- Encrypted transfer: The connection data of each depot is stored locally in its DepotTopology.json file and transferred to the depot in encrypted form.
Terms
| Term | Description |
|---|---|
| Depot Topology | The hierarchy of all depots in your environment. A depot first connects to its parent. If the parent is unavailable, it connects to the failover server defined for it. |
| Connection Profile | Defines how assigned depots reach a depot or the Master Server: protocol, priority, and, if used, certificate settings. |
| Tag | Assigned to objects and depots. Controls which objects are synchronized to which depot. |
| DepotTopology.json | The local configuration file of a depot, stored under C:\EmpirumAgent\Configuration\DepotTopology.json. It describes how the depot connects and which Tags are assigned to it. When the configuration changes, the file is transferred to the depot in encrypted form via the Service Bus. |
In this release, "object" refers exclusively to a Software Package. Further object types will follow in later releases. See Limitations.
As long as a depot has not received a DepotTopology.json, it continues to use the Agent Template for its connection. The new settings only take effect after you save them in the EMC.
Synchronization Mode
You define the general synchronization behavior in the EMC under Extras → Settings → Depot Sync.
| Mode | Behavior |
|---|---|
| Standard | All existing and new objects are always synchronized to all depots automatically. No Tag assignment is required. You only configure the Depot Topology and the Connection Profiles. |
| Tag-based | Objects and depots receive Tags. A depot only receives objects that share at least one Tag with it. New packages do not receive a Tag automatically. |
Prerequisites
Before you start the setup, check that the following requirements are met.
| Area | Requirement |
|---|---|
| Infrastructure | Enterprise Service Bus based on Azure Service Bus or RabbitMQ. Required firewall ports opened. Webservice Configuration with IIS web server (HTTP/HTTPS). |
| Software | Depot Sync 4.0 imported (may only be available via the Marketplace). UEM Agent 2610.1.2 or later. Service Bus Service 26.2 or later on the Empirum Server. |
| Permissions |
EMP_M_DEPOT_SERVER in the EMC. Administrator rights for local PowerShell commands on the depot servers. |
| Depot servers | The Empirum Server is always the base depot (the Master Server). You configure additional depot servers by assigning the Depot Server role and installing the Subdepot packages. |
Limitations
- Only Software Packages support Tags. Further object types will follow in future releases.
- Agent MSI files and OS disk configurations are always synchronized and cannot receive Tags.
- Directory and file excludes are no longer applied during package synchronization.
Initial Setup
The setup consists of two procedures: first, you set up a single depot in Standard mode. Then, optionally, you switch it to Tag-based synchronization.
Set Up a Single Depot
This procedure puts a depot into operation under Depot Sync 4.0. All objects are synchronized to all depots.
- Set Standard mode: In the EMC under Extras → Settings → Depot Sync, activate or verify Standard mode.
- Assign the Depot Server role: Assign the Depot Server role to the computer object.
- Configure the Depot Sync variables: Set up the Variable Configuration MX42 UEM Depot Management v4 for this depot.
- Configure the Subdepot variables: Set up the Subdepot-specific variables.
- Configure the Webservice variables (optional): Set up the variables that the Webservice Configuration package requires on this depot.
- Create a Connection Profile: Create a Connection Profile with the connection data this depot uses to reach its parent.
- Add the depot to the Depot Topology: Place the depot below its parent in the Depot Topology.
- Assign the Connection Profile: Assign the Connection Profile created in step 6 to the parent.
- Create assignments: Create an assignment that bundles the UEM Agent, the relevant Variable Configurations, the objects, Depot Sync 4.0, and the depot server object. Repeat the same assignment setup for the parent.
- Install the Subdepot package: Install it on the parent and the depot.
- Install Webservice Configuration (optional): Install it on the parent and the depot.
- Install Depot Sync 4.0: Install the Depot Sync 4.0 package on the depot server.
- Save the changes: Save the settings in the EMC.
The Connection Profile automatically uses the variables assigned in steps 3 to 5. You do not need to enter this connection data again in the profile.
The DepotTopology.json is only generated and used after you save. From then on, the depot is managed entirely through the Depot Topology.
Switch a Depot to Tag-Based Synchronization
The starting point is a running depot set up as described above. With the following steps, you control precisely which objects this depot receives.
- Set Tag-based mode: In the EMC under Extras → Settings → Depot Sync, activate Tag-based mode.
- Create Tags: In the Depot Sync area of the EMC, open the Manage Tags tab and create the Tags that control which packages are synchronized to which depots. The Global Tag is predefined, cannot be deleted, and is initially assigned to all objects. You can create and delete additional Tags. The right column shows which objects and depots each Tag is assigned to.
- Assign Tags to packages: Assign the appropriate Tags to each package that you want to synchronize selectively. In the Depot Sync area of the EMC, open the Assign Tags/Objects tab. Select one or more Tags in the left column and one or more objects in the right column to add or remove the assignment. You can also assign Tags via drag and drop.
-
Assign Tags to the depot: In the Depot Sync area of the EMC, open the Depot Topology tab. You can assign Tags in two views:
- Diagram view (default): Assign Tags via drag and drop or in the properties pane on the right.
- Grid view: Useful for environments with many depots. Assign Tags via the context menu or in the properties pane on the right.
- Save the changes: Save the settings in the EMC.
New packages do not receive a Tag automatically. When you switch from Standard to Tag-based mode, all existing packages and depots automatically receive the Global Tag. See Migration from Depot Sync 3.x.
If you assign a Tag to a depot whose parent does not have this Tag, the Tag is implicitly assigned to the parent as well. Otherwise, the objects would not be available there. The Master Server always has all Tags assigned and therefore receives all objects.
Add Another Sub-Depot
Repeat the procedure described above for each additional level of the hierarchy. The key difference for a sub-sub-depot: its Connection Profile and Tag assignments refer to its parent depot, not to the Master Server. The Depot Topology resolves multi-level relationships at every level according to the same principle.
Migration from Depot Sync 3.x
Before the migration, make sure that the synchronization mode in the EMC is set to Standard.
Step-by-Step Migration
You migrate depots individually and define the Depot Topology and Connection Profiles depot by depot. Once all depots are migrated, you can set up Tag-based synchronization.
Tag-Based Object Synchronization
When you switch from Standard to Tag-based mode, all existing packages and depots automatically receive the Global Tag. This preserves the previous behavior, where every package is synchronized to every depot. You can then refine the selective synchronization at your own pace, for example by removing the Global Tag from a package and replacing it with a more specific Tag.
In Tag-based mode, new packages do not receive the Global Tag automatically.
Troubleshooting
Synchronization Shows "Cancelled"
Possible cause: The certificate is missing, invalid, or expired.
If the Service Bus cannot find a valid certificate to encrypt the DepotTopology.json, it blocks all further synchronizations to this depot. The sync status view shows these synchronizations as Cancelled until the certificate issue is resolved.
The Cancelled status in the sync status view is the main indicator of a certificate issue.
Possible solutions:
- Restart the UAF (Universal Agent Framework) service on the affected depot.
- Delete the value stored for the depot from the table
EmpirumDepotTopologyCertificate. Then make a temporary change to the depot configuration, for example by assigning a Tag that has no objects assigned.
DELETE FROM EmpirumDepotTopologyCertificate
WHERE Computer = '<depot computer name>'Back up the Empirum database before running SQL statements directly against it, and make sure the WHERE clause targets only the affected depot.
DepotTopology.json Is Not Created
Check the following in order:
- Is the Depot Topology saved in the EMC?
- Is the Service Bus reachable?
- Is Depot Sync 4.0 installed on the depot?
FAQ
Which object types are supported in this release?
Only Software Packages within the Packages sync job are synchronized via Tags. Patches and drivers are handled as before. Further object types, such as OS sources, language packs, and drivers, will move to the Tag-based model step by step in future releases.
Does Depot Sync 4.0 mean more administrative effort?
The initial setup introduces additional concepts compared to the previous depot server configuration (Depot Topology, Connection Profiles, Tags) and is therefore more extensive. In return, you get much more precise control over what is synchronized where.
What is the main benefit of the Depot Topology and Connection Profiles?
Selective, Tag-based package distribution combined with a centrally managed Depot Topology, instead of a complete depot server configuration and Agent Template settings per depot.
Do I need a Depot Sync 3.x structure to set up Depot Sync 4.0?
No. An existing Depot Sync 3.x structure is not a prerequisite for Depot Sync 4.0.
Why do Depot Sync 3.x and Depot Sync 4.0 exist in parallel?
Depot Sync 3.6 contains important fixes for customers who cannot move to Empirum 26.2 immediately or who need more time to migrate all depots to Depot Sync 4.0. In the medium term, there will be only one version.
How long will EmpSync be supported?
EmpSync is in maintenance mode and is expected to be removed with version 27.1.