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 migrate your policies and agents.

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

This guide describes how to use the Deep Security Manager and Workload Security UI to perform migration. If you prefer to use the API:

  • Read through this guide for general requirements and tips.
  • Create an API key as described in this guide, then follow the API document to create a Workload Security Link.
  • To create a policy migration task, follow the API document.
  • To check the migration status, use an HTTP GET call to retrieve the status from /policymigrationtasks/{taskID}. For details, see Workload Security Automation Center.
  • To create an agent move task, follow the API document.

Prerequisites and limitations

  1. If you're migrating policies, check that you're running 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.

  2. If you're migrating agents:
    • Check that you're using Deep Security Manager 20.0.321 (20 LTS 2021-01-26) or later
    • Check that you're using Deep Security Agent 20.0.0-2419 or later
    • 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.
  3. If you haven't done so already, sign up for Trend Micro Cloud One.

You're now ready to Create an API key and then Migrate policies and agents using the migration tool.

Create an API key

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.

Migrate policies and agents

The Deep Security migration tool steps you through configuring the link to Workload Security, migrating your policies, and migrating your agents.

  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 Link to Workload Security Account page that appears:

    Screenshot of "Link to Workload Security Account" window

    1. Enter the API key that you created in the previous section.
    2. Select the region where your Workload Security account is located.
    3. Select Save.

    If you previously set up a connection between Deep Security and Workload Security and want to change the link, make sure all migration-related tasks using the previous connection are completed before changing the link. Otherwise, you may experience unexpected behavior.

    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.<region>.cloudone.trendmicro.com), please configure the proxy for Workload Security.

  3. The Migrate to Workload Security page appears with the Migrate Configurations tab selected.

    Screenshot of the migration tool with Migrate Configurations tab displayed

  4. To migrate policies:
    1. Select Migrate. The migration tool targets all policies on Deep Security Manager.

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

    2. The migration tool display a status. You can also check in Workload Security by going to the Policies page. Any migrated policies will appear in the list, showing a timestamp and the Deep Security Manager hostname.

      These are the possible statuses:

      • Requested: A policy migration task to Workload Security has been requested but the policy migration hasn't started yet.
      • In Progress: Policies are being migrated to Workload Security. 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.
      • Complete: Policies have been migrated successfully to Workload Security.
      • Failed: Policies have failed to migrate to Workload Security for some reason. Check the error code:
        • Error code 303: The policies being migrated reference one or more rules that are not available on Workload Security. Please ensure that Deep Security Manager and Workload Security are using the same Rule Update version.
        • Other error codes less than 900: There is a failure from Workload Security. Please contact support.
        • Error codes greater than or equal to 900: 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.
  5. When the policy migration has finished, migrate your agents:
    1. On the Migrate to Workload Security page, select the Migrate Agents tab.
    2. Select Migrate using Computers page. The Deep Security Computers page is displayed.
    3. Select one or more computers that you want to migrate.
    4. Select Actions > Migrate to Workload Security.
    5. 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 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-level overrides.

    6. Check the move status.
    7. 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