Appendix: Sophos Migration Agent

Sophos Migration Agent is a command-line tool for distributing migration packages to the update locations used by computers that are managed by Sophos Enterprise Console.

Note A migration package contains the Sophos Central agent installer and other files needed for migration.

Each time you use Sophos Central Migration Tool to migrate computers, it creates a migration package in a "CloudMigrationPackage" folder in the local default Sophos Update Manager share. For example:

\\MySecServer\SophosUpdate\CloudMigrationPackage

You can use Sophos Migration Agent to deploy that migration package to update locations managed by remote instances of Sophos Update Manager.

Installation and updates

Sophos Migration Agent is available on all servers which have SUM installed.

Sophos Migration Agent is in the folder %programfiles(x86)%\Sophos\MigrationAgent (64-bit) or %programfiles%\Sophos\MigrationAgent (32-bit). It's installed and updated as part of the SUM self-update process.

Rights needed

Sophos Migration Agent must run as an account that has local administrative rights and user impersonation privileges.

If User Account Control (UAC) is on and you want to run the agent interactively, open the command prompt with Run as administrator and run the agent from it.

Command-line parameters

SophosMigrationAgent [-p[ackagepath] <path>] [-a[ction] <action_name>] [-p[ackagepath] <path>] [-d[ebug]] [-t[raceoutput] <trace_method>] [-c[idpath] <path>] [-h[elp]]

-a sets the action to be performed. This can be "deploy" (the default) or "cleanup". Deployment puts a package in every CID (Central Installation Directory) updated by the Sophos Update Manager. Cleanup removes the package.

-p lets you specify the path (either UNC path or a local path) to the root folder of the package that needs to be deployed. The path can't contain any Unicode characters that can't be mapped to English encoding.

-d sets the trace verbosity to debug level. We recommended that you always use this parameter when running in interactive mode.

-t selects targets for the trace output: file, console, all, none. By default, trace output is directed both to the console and to a trace file.

-c restricts deployment to a single CID. The path can't contain any Unicode characters that can't be mapped to English encoding.

-h prints a brief description of the parameters and usage.

Package deployment

Package deployment is the default action.

This downloads a migration package, reads the local Sophos Update Manager configuration file, and deploys the package to every CID location updated by Sophos Update Manager.

You must specify a path (either UNC path or a local path) to the root folder of the package that needs to be deployed. For example:

"%programfiles(x86)%\Sophos\MigrationAgent\SophosMigrationAgent.exe" –p “\\MySecServer\SophosUpdate\CloudMigrationPackage”

SophosMigrationAgent.exe –packagepath “c:\LocalStorage\MigrationPackage” –a deploy

SophosMigrationAgent.exe –p “\\SomeServer\SomeShare\SomeFolder\MigrationPackage” –action deploy

Note If access to UNC paths is restricted, an agent on a remote Sophos Update Manager can't get the package from another server. Copy the contents of CloudMigrationPackage to a new folder on the remote Sophos Update Manager and use -p with the new, local path.
Note The path can't contain any Unicode characters that can't be mapped to English encoding.
The result of the operation is kept in the registry along with the rollout number.
Note The rollout number is incremented each time the package is updated. The number is checked during migration to ensure that out-of-date migration packages aren't used.

You can use the -c parameter to restrict deployment to only one of the CIDs updated by the local Sophos Update Manager. For example:

SophosMigrationAgent.exe –p “\\SomeShare\SomeFolder\MigrationPackage” –c \\SomeOtherServer\SomeFolder\CIDs\S001.

The path must match exactly one of the CID paths from the Sophos Update Manager configuration file. To find out the paths stored in the configuration file, do as follows:

  • Use a text editor to open %programfiles(x86)%\Sophos\Update Manager\config.xml (64-bit) or %programfiles%\Sophos\Update Manager\config.xml (32-bit).
  • Search for the XML element tag <NewCidDir>.
Note CIDs in the default share of Sophos Update Manager are not shown as UNC paths but as local file paths. For example <NewCidDir>C:\ProgramData\Sophos\Update Manager\Update Manager\CIDs\S001</NewCidDir>.
Note The path can't contain any Unicode characters that can't be mapped to English encoding.

Results of actions

The operation is successful if the package is deployed without problems to all the CIDs managed by the local Sophos Update Manager.

If the operation is successful, Sophos Migration Agent will subsequently skip deployment unless the source package content has been updated with higher rollout number.

If new shares or CIDs have been added since the last successful deployment, we recommend that you use the Sophos Central Migration Tool menu option Actions > Refresh Migration Packages to generate the package again with higher rollout number. Then run Sophos Migration Agent to deploy it to the new update locations.

The operation is reported as unsuccessful if it fails to deploy to one or more CIDs. The error code and the package rollout number are reported to Sophos Enterprise Console by a prefix added to the computer description string.

Logging

You can find the log file here: %ProgramData%\Sophos\MigrationAgent\Logs\MigrationAgent.log.