Migrate agents to Workload Security

This is one part of the process for migrating from Deep Security to Workload Security. For a complete picture of the migration process, see Migrate from Deep Security to Workload Security.

Prerequisites

  • Check that you're using Deep Security Manager 20.0.321 (20 LTS 2021-01-26) or later for migrating via APIs, or Deep Security Manager 20.0.513 (20 LTS Update 2021-10-14) or later for migrating using the Deep Security Manager migration tool.
  • Check that you're using Deep Security Agent 20.0.0-2419 or later. Then, in the Workload Security console, go to Administration > Updates > Software > Local and make sure your account has the corresponding Deep Security Agent package.
  • Check that your agents are running on platforms that support migration:
    • The Agent platform support table lists agent platforms supported by Deep Security Manager 20.
    • Migrating agents is currently fully validated only on Windows and Linux platforms on Intel architecture.
    • Migrating agents is not supported on Windows 2008 32-bit.
  • Due to feature differences between Deep Security Manager and Workload Security, disable these features before migrating agents.
  • If you haven't done so already, complete the earlier steps described in Migrate from Deep Security to Workload Security, including creating a Trend Micro Cloud One account, creating an API key, and preparing a link to Workload Security.

Migrate agents using the migration tool

  1. In upper-right corner of the Deep Security Manager console, select Support > Migrate to Workload Security.

    Screenshot of Manager window with Support menu displayed

  2. On the Migrate to Workload Security page that appears, select the Agents tab.
  3. Select Migrate using Computers page. The Deep Security Computers page is displayed.
  4. Select one or more computers that you want to migrate.
  5. Select Actions > Migrate to Workload Security.
  6. In the dialog box that appears, specify the settings that you want applied to the agents when moved, and then select Migrate:

    • Security Policy: If you have migrated your Deep Security policies to Workload Security and want to keep the same policy applied to the migrated agent, select Assign migrated policy. If you want to assign a different policy, choose Select a policy from Workload Security and select the new policy.
    • Computer Group: The computer group where the agents will be put in Workload Security.
    • Relay Group: All agents will be assigned to the Primary Relay Group in Workload Security.
    • Proxy to contact Workload Security Manager: Select a proxy if agents need one to contact Workload Security.
    • Proxy to contact Relay(s): Select a proxy if agents need one to contact relays on Workload Security.
    • Migrate with existing hostname, display name, and description: Select this to use the existing hostname, display name, and description for the migrated agent.
    • Migrate with settings override at computer level: Select this to migrate any settings that have an override at the computer level. This does not include rule assignments.
  7. Check the move status.
  8. If you run into problems, check Troubleshooting

Check the move status

The status of move tasks is available from the API response, computers page, and system events. The move status is also a search criteria in smart folders.

The original state of a move task is that the agent is managed by an on-premises Deep Security Manager.

Diagram of move agent status

Status Description How to recover to original state
Move Requested

A move task to Workload Security has been requested.

The move task has been accepted by Deep Security Manager, but not yet sent to the agent.

N/A
Moving

Computer is being moved to Workload Security.

The agent has accepted the move task, and is moving to Workload Security.

N/A
Move Complete

Computer has been moved successfully to Workload Security.

Deep Security Manager is able to identify that the moved agent is activated on Workload Security.

Manually reactivate the agent back to Deep Security Manager.

Note that the agent has already trusted the Workload Security public certificate. You must remove the ds_agent_dsm_public_ca.crt file manually before activating the agent back to Deep Security Manager.

Move Failed

Computer was not moved to Workload Security due to a connectivity issue from the agent to Workload Security.

The agent has rejected the move task while performing its pre-check.

Before trying the move again:

  • Check that all parameters specified for the move are correct, including the account information, activation token, public CA certificate, and proxy settings.
  • Check that there are no networking/firewall settings preventing the agent from reaching Workload Security.
  • Use the CLI to create an agent diagnostic package, which will include a ds_agent.log file containing information about the failed move. For instructions on creating diagnostic packages, see Create a diagnostic package and logs.

Clear Warnings on the console.

The agent is still managed by Deep Security Manager.

Move Failed
(No response)

Computer was not moved to Workload Security because the agent did not respond to the move task in a timely manner.

Before trying the move again:

  • Check that the agent is up and running.
  • Check that the agent can communicate properly with Deep Security Manager.

Clear warnings on the console.

The agent is still managed by Deep Security Manager.

Move Failed
(Failed to activate)

The move to Workload Security failed due to an activation issue and was rolled back.

The pre-check passed, but the agent was unable to activate to Workload Security.

Before trying the move again:

  • Check that the Workload Security Link is up to date.
  • Check that all parameters specified for the move are correct, including the account information, activation token, public CA certificate, and proxy settings.
  • Use the CLI to create an agent diagnostic package, which will include dsa_move.log and dsa_control.log files containing information about the failed move. For instructions on creating diagnostic packages, see Create a diagnostic package and logs.

Clear warnings on the console.

The agent is still managed by Deep Security Manager.

Move Failed
(Unmanaged)

The move to Workload Security failed due to an activation issue, and the move could not be rolled back automatically. The computer is in an unmanaged state.

The pre-check is passed, but the agent was unable to activate to Workload Security.

An agent in this state may have encountered unknown issues during roll back, and the agent needs manual intervention.

To troubleshoot this issue:

  • Look into the dsa_move.log file, which contains information about the failed move.
  • Manually restore the agent or reactivate the agent. See the Troubleshooting section for more details.

Before trying the move again:

  • Check that the Workload Security Link is up to date.
  • Check that all parameters specified for the move are correct, including the account information, activation token, public CA certificate, and proxy settings.

Manually restore the agent back to Deep Security Manager.

The agent is still protecting the host computer but is not being managed by Deep Security Manager.

See the Troubleshooting section for more details.

Use Smart Folder to view move status

  1. From the Smart Folder Editor, expand the Search Criteria.
  2. In the first drop-down list, select the property Status: Move Status.
  3. In the second drop-down list, select a value such as Move Complete or Move Failed.

Smart folder query showing move status

Troubleshooting

Restore an unmanaged agent manually

Check the dsa_move.log file to identify the root cause of the move failure. The agent restore may have failed because the agent failed to stop or failed to start.

Agent failed to stop

If the agent failed to stop during the restore process, the following error message will be seen in the logs:

Unable to stop the agent. Agent restore failed.

Here is how to restore the agent:

  1. Stop the agent service.
  2. Restore the agent backup.
    1. Locate the agent work directory.
      • Agent work directory in Windows: %ProgramData%\Trend Micro\Deep Security Agent\
      • Agent work directory in Linux/Unix: /var/opt/ds_agent/
    2. Within that directory, the backup name starts with backup_ and ends with the date. For example: backup_2021-05-11_20.11.45
    3. Remove everything from the agent work directory except for the diag and backup_* directories.
    4. Copy everything from the backup_* directory to the agent work directory.
  3. Start the agent service.
  4. Send a heartbeat to Deep Security Manager using dsa_control -m
  5. Remove the backup_* directory if the agent was restored successfully (activated successfully with Deep Security Manager).
Agent failed to start

If the agent failed to start during the restore process, the following error message will seen be in the logs:

Unable to start the agent. Agent restore failed.

Here is how to restore the agent:

  1. Start the agent service.
  2. Send a heartbeat to Deep Security Manager using dsa_control -m

Other methods for migrating agents

If your environment contains sufficient automation tools, you can reactivate agents by extracting the activation command from deployment scripts within the Workload Security console. New hosts that don't have an agent should run the entire script. Hosts with existing up-to-date agents can just run the dsa_control command located in a comment at the end of the deployment script. If proxies are in use, note the several lines preceding this command and execute them with the correct values prior to running the activation command. Reactivation does not require a reboot or cause loss of protection during the process.

Environments without sufficient automation infrastructure can use the Deep Security MoveAgent API. This reactivates agents automatically, using the Workload Security Link configured for the target Workload Security account. This method requires Deep Security Manager 20.0.321 (20 LTS 2021-01-26) or later and Deep Security Agent 20.0.0-2419 or later. For instructions, Migrate using the Deep Security and Workload Security APIs.

We recommend that you enable the option in Workload Security to automatically upgrade agents on activation to ensure you will get the full security control provided with the latest agent. The minimum agent version available in each Trend Micro Cloud One region is different. We recommend using the latest agent version whenever possible, but if you require an older agent version that is not available in your account, please contact Trend Micro support.