Migrate to Workload Security

If you are currently using Deep Security, you can follow the instructions in this article to automate some aspects of the migration process. You can use features provided by Deep Security to automate these migration tasks:

  • Policy migration
  • Agent migration

This guide will be updated as migration features are added to Deep Security.

Requirements

  1. Check that you're running a version of Deep Security that supports migration tasks:
    • Migrating policies requires Deep Security Manager 20.0.463 (20 LTS Update 2021-07-22) or later

      If you don't want to upgrade to a supported Deep Security 20 version to migrate policies, this Deep Security 12 article describes how to migrate policies by exporting them to XML and then importing via API into Workload Security.

    • Migrating agents requires Deep Security Manager 20.0.321 (20 LTS 2021-01-26) or later and Deep Security Agent 20.0.0-2419 or later
  2. If you haven't done so already, sign up for Trend Micro Cloud One.
  3. Set up a link between Workload Security and Deep Security.

You can then Migrate agents and/or Migrate policies.

Set up a link between Workload Security and Deep Security

To migrate an object -- an agent or a policy -- managed by Deep Security Manager to Workload Security, set up a link from Workload Security to an on-premises Deep Security Manager. The link enables the Deep Security Manager to connect to one Workload Security account, perform migration operations, and monitor their status.

  1. In Workload Security, follow the instructions to create an API key. Assign the predefined role "Deep Security Migration" to the API key. The "Deep Security Migration" role is preconfigured and managed by Workload Security with rights to perform migration of agents or policies. The associated rights may change in the future, as additional migration features are implemented.

    We strongly recommend that you do not assign the "Full Access" role to the API key. This role will work, but it creates security concerns.

  2. Follow the Deep Security API document to create a Workload Security Link with the API key created in the section above.

    Each Deep Security Manager tenant allows only one Workload Security Link.

During the Workload Security Link creation, Deep Security Manager connects to Workload Security to authenticate the link and retrieve information. If the Deep Security Manager installation requires a proxy to connect to Workload Security (https://workload.us-1.cloudone.trendmicro.com), please configure the proxy for Workload Security.

Migrate agents

To migrate your agents to Workload Security:

  1. Check that your agents are running on platforms that support migration. See Which platforms support agent migration?
  2. Disable features that aren't supported in Workload Security. See Feature limitations
  3. Create a move task
  4. Check the move status. You can Use Smart Folder to view move status
  5. If you run into problems, check Troubleshooting

Which platforms support agent 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.

Feature limitations

Due to feature differences between Deep Security Manager and Workload Security, disable these features before migrating agents.

Create a move task

Follow the API document to create a move task. This task will move the agent to the Workload Security tenant configured in the Workload Security Link.

A move task targets only one agent. In order to move multiple agents, multiple API calls to Deep Security Manager are required.

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

Migrate policies

To migrate your policies to Workload Security:

  1. Create a migration task.
  2. Check the migration state.
  3. If you run into problems, check Troubleshooting

Create a migration task

Follow the API document to create a migration task. This task moves the policies to the Workload Security account configured in the Workload Security Link.

The migration task targets all policies on Deep Security Manager. There is no need to create multiple tasks.

Application Control settings are not migrated. Network-dependent objects and settings (proxy settings, syslog configurations, and so on) may not be migrated.

Check the migration state

In Workload Security, go to the Policies menu. Any migrated policies will appear in the list, showing a timestamp and the Deep Security Manager hostname.

To see the migration status, use an HTTP GET call to retrieve it from /policymigrationtasks/{taskID}. For details, see Workload Security Automation Center.

Status Description
Requested

A policy migration task to Workload Security has been requested.

The policy migration task has been accepted by Deep Security Manager, but not yet started to migrate the policies.

In Progress Policies are being migrated to Workload Security.
Complete Policies have been migrated successfully to Workload Security.
Failed

Policies have failed to migrate to Workload Security for some reason.

Please check the Troubleshooting section.

Troubleshooting

  • If the status is "Failed":
    • If the error code is less than 900, it is a failure from Workload Security. Please contact support.
    • If the error code is greater than or equal to 900, it means the Deep Security Manager has a problem communicating with Workload Security. Please make sure the Workload Security Link is correctly configured, or check server0.log for details.
  • If the status stuck in "In Progress", it means the Deep Security Manager cannot get the response from Workload Security. Please check the network configuration.