Updating a Running System: Shadow Copy

FlexNet Manager Suite 2023 R1 (On-Premises)

FlexNet Manager Suite is designed to be a high-availability system. One aspect of that is to allow updates to parts of the system without having to interrupt normal operations.

On the batch server, FlexNet Manager Suite uses a technique called "shadow copying" to ensure that its executables can run continuously even when those same executables or their dependent assemblies need to be updated. Shadow copying is a core feature of the Microsoft .NET runtime. The shadow copy process works like this:

Whenever an assembly (a part of the product code) is to be executed, it is first copied to a secondary location.
The assembly copy is then executed from the secondary location. As a normal part of code operation, that running copy of the assembly is locked and cannot be updated.
However, the original assembly is not in use, remains unlocked, and may be updated if necessary (even while the locked copy is executing).
Before each invocation of the copied assembly, a check is made to see whether the original source assembly has been updated since the copy was made; and if so a new (replacement) copy is made, and used for subsequent execution.
The shadow copy does not change anything about the operation of the assembly. For example, the same values are read from the Windows registry when appropriate; log files are written to the same locations; and so on.
As more space for copying assemblies is required, the underlying Microsoft .NET runtime automatically cleans up copied assemblies that are no longer in use, restricting the size of the disk cache used for copied assemblies.

This process allows for the original assemblies to be updated without interrupting operation of FlexNet Manager Suite, and also ensures that the latest available code assembly is used at each invocation.

Tip: The test for an updated assembly is a direct comparison of:

The file date and time of each assembly in the application directory
The file date and time of the matching assembly in the shadow copy directory.

If the assembly in the application directory has a later date/time, it is freshly copied to the shadow copy directory. This makes upgrades to later versions very straight-forward; but it does not provide for rolling back to a previous version of an assembly. If you need to roll back an assembly to a previous version, you must manually edit the date and time of that previous assembly in the application directory to values (slightly) more recent than the date and time of the current version in the shadow copy directory. Once the date/time is adjusted to be more recent, the next invocation of the assembly triggers the copy of the older version of the assembly into the shadow copy directory. Leaving only a small gap between the date/time settings reduces any risk of 'skipping' an intermediate update.

Where shadow copying is used

On the batch server (or, in smaller implementations, the combined server that is hosting this functionality), FlexNet Manager Suite uses shadow copying for:

The FlexNet batch scheduler
The FlexNet batch processor
Those batch server scheduled tasks and program shortcuts that invoke either of the above
All child processes invoked by the FlexNet batch processor.

Only .NET assemblies and executables from the directory InstallDir\DotNet\bin and its descendants are shadow copied. (The placeholder InstallDir stands for the installation folder for FlexNet Manager Suite on the batch server, for which the default location is C:\Program Files (x86)\Flexera Software\FlexNet Manager Platform\.)

Note: If you require high-availability update behavior for your implementation of FlexNet Manager Suite, any custom scheduled tasks you have added that run executables from InstallDir\DotNet\bin should be updated with the alternate shadow copy syntax described below.

The cache location where assemblies are copied before invocation is fixed for a given account running the process, and is C:\Users\useraccount\AppData\Local\assembly. (The placeholder useraccount stands for the account used to invoke the process. For normal operations of the batch server, this is the service account running FlexNet Manager Suite, for which the name suggested in the installation process was svc-flexnet.)

Using shadow copy

Whenever you want to invoke a target executable using the shadow copy mode, you do so by first invoking a host executable that takes care of the required copying and then executes the target process in its own application domain. This host executable has the capability either to run a .NET executable or to host a .NET Windows service.

In fact, there are three variations of the host executable for use in different contexts:

ShadowHost.exe – used to execute console-based assemblies including the FlexNet batch scheduler and FlexNet batch processor. The batch processor service also uses ShadowHost.exe (and ShadowHost32.exe, described below) to invoke other processes that it runs.
ShadowHostWin.exe – used to execute Windows Forms-based assemblies. You can also use this variation in the command line for Windows Scheduled Tasks where you do not want the executing process to display a console window.
ShadowHost32.exe – used to execute assemblies that can only be run in 32-bit mode, such as the FlexNet Business Importer (MGSBI.exe).

All three variations of the ShadowHost executable listed above are available in the InstallDir\DotNet\bin folder on the batch server.

Tip: A .NET console or Windows executable can also be executed in shadow copy mode. This is only necessary when the executable in question is part of the FlexNet Manager Suite product that resides in InstallDir\DotNet\bin.

The command-line format to use shadow copy is straightforward: take the existing command line that you expect to run, and precede it with the variation of ShadowHost (as listed above) that is appropriate to your context.

Tip: It is not mandatory to use the shadow copying technique, and all existing command lines (without the ShadowHost variant) continue to operate as they did. However, use the shadow copying technique described here when you want a high-availability system that allows patches to the .NET assemblies and executables used in FlexNet Manager Suite without interrupting operations.

Syntax

ShadowHost[Win|32].exe executable_name executable_arguments

When executing a process through the console, or programmatically through a scheduled task, the variant of the ShadowHost executable that should be used is determined by how that process is to interact with the rest of the system. Consult the list above to determine which executable variant is appropriate.

Examples

Execute the compliance reader to transfer data from staging tables to production and calculate license consumption:
```
ShadowHost.exe ComplianceReader.exe -it Writers
```
Run the Business Importer (a 32-bit executable) to import data through a custom adapter:
```
ShadowHost32.exe MGSBI.exe /config adapter.xml
```
Specify a Microsoft scheduled task to run all inventory imports and perform license consumption calculations:
```
Executable: ShadowHostWin.exe
Arguments: BatchProcessTask.exe run InventoryImport
```

Troubleshooting shadow copy

If you are troubleshooting an issue that may relate to one of the ShadowHost executables, you can enable logging.

Important: Shadow copy log files continue to grow over time and are not cleaned up automatically. Best practice is to enable logging during your troubleshooting exercise, and to disable it again afterward, and perhaps even clean up the log files that were generated.

Log file location details on your batch server (or, in smaller implementations, your application server):

Once enabled, ShadowHost[Win|32] logging writes diagnostic information to ComplianceLoggingPath\ShadowHost.
The default value for the placeholder ComplianceLoggingPath is %ProgramData%\Flexera Software\Compliance\Logging.
You can modify the value for ComplianceLoggingPath by creating a REG_SZ registry key at SOFTWARE\WoW6432Node\ManageSoft Corp\ManageSoft\Compliance\CurrentVersion\LoggingBaseDirectory, and setting it to your preferred path. (Removing this key again restores the default value.)

When you enable or disable logging, the change affects only new processes that start after the change. It does not affect any processes that are already running. Such long-running processes include both the batch processor and the batch scheduler, so that to turn logging on or off for these services, you must stop them and restart them.

Warning: Abruptly stopping the batch processor cancels any batch processes that are currently running (for more information, see Monitoring, Stopping, and Restarting the Services).

You can avoid canceling currently-running processes by using the following steps to turn logging on (or off) for these two services:

Pause the batch scheduler to stop it sending new tasks to the batch processor:
```
ShadowHost.exe BatchProcessTaskConsole process-dispatch -p
```
Monitor the running tasks, repeating until no tasks are listed as executing:
```
ShadowHost.exe BatchProcessTaskConsole.exe list-tasks
```
Tip: You can also review BatchProcessExecution/BatchProcessExecutionInfo in the database.
Stop the services FlexNet Manager Batch Process Scheduler and FlexNet Manager Batch Processor.
Create the following DWORD key on your batch server, setting it to a non-zero value:
```
SOFTWARE\WoW6432Node\ManageSoft 
    Corp\ManageSoft\Compliance\CurrentVersion\ShadowHostTracingEnabled = 1
```
Tip: To disable logging again, set this key value to zero, or remove it from the registry.
Restart the services FlexNet Manager Batch Process Scheduler and FlexNet Manager Batch Processor.

Conduct your troubleshooting, and when logging is no longer needed, use a similar process to pause scheduling, stop both services, turn off logging, and restart the services again. Remember to clean up log files that are not longer needed.

FlexNet Manager Suite (On-Premises)

2023 R1