Introduction

This document describes how to manage the transfer of systems protected with Trellix Drive Encryption from one Trellix ePolicy Orchestrator - On-prem server to another whilst preserving user assignments, user token, and other data.

In this document, Drive Encryption 7.x.x refers to Drive Encryption 7.1.3, 7.2.0, and above.

Overview

The client system transfer functionality is only available in Drive Encryption version 7.x.x. With earlier versions, transferring a system from one Trellix ePO - On-prem server to another will replace the user assignments and user token data on the system with data from the destination server, potentially losing user assignments and changing user credentials in the pre-boot environment.

About this document

This document is broken into several sections. The initial sections describe how to manage the transfer of systems between Trellix ePO - On-prem servers, including pre-requisites and considerations of scalability to avoid server overload. The later sections give some helpful case studies to show how common Drive Encryption configurations can be managed.

Trellix Drive Encryption 7.4.x Client Transfer Migration Guide3

2 | Introduction

Client system transfer operation

Drive Encryption 7.x.x provides the Trellix ePO - On‑prem administrator with a new capability to allow systems to be transferred from one Trellix ePO - On‑prem server to another whilst preserving user assignments and user data.

Overview

If the feature is enabled, a system installed with Drive Encryption 7.x.x will detect a server change, and request that the new Drive Encryption 7.x.x managing server automatically assigns users to the system within the context of the new managing server. Once the assignment is successful, the system will send its user token data up to the new managing server.

Terminology

The original managing Trellix ePO - On‑prem server is called the source server. The new managing ePO server is called the destination server.

Fundamentals

The transfer process is a system-initiated process. During the first policy enforcement under the control of the destination server, the system receives a manifest of users that are already assigned to it in the context of the destination server.

The system calculates the difference between the received manifest and the current set of users on the system (those that were assigned in the source server) to form List A. If List A contains at least one user (and fewer than a configurable maximum number), the system sends List A to the destination server, requesting that it assigns the users in List A directly to the system. An event is sent to the destination server at this point to state that a system transfer has started.

Because the destination server will assign users directly to the system (and not to a parent branch), it is important that any required branch-level user assignments are made in the destination server prior to system transfer being instigated - failure to do so will result in these users being assigned directly to the system making future user management more complex.

Once the assignment of the users in List A has been successfully made in the destination server, at the next ASCI the system will push user token data for the newly assigned users up to the destination server, along with system encryption and recovery keys, completing the user data transfer process. At this time, an event is sent to the destination server to state that the system transfer has completed successfully.

If the number of assignments that need to be made exceed a configurable maximum, the transfer will fail and an appropriate error event will be sent up to the destination server.

It is clearly important that the destination server has one or more appropriately configured Active Directory servers to ensure that users can be found and then assigned within the destination server.

It is also equally important to configure the Drive Encryption policies in the destination server to ensure that they match those

2 | Introduction

from the source server; failure to do so might lead to systems deactivating or changing their behavior.

Environments that use policy-assignment rules to assign user-based policies based on complex rules should take extra care to ensure that rules are appropriately defined in the destination server; failure to do so might lead to changes in the logon experience for affected users.

User directory

The Trellix ePO - On-prem User Directory is a directory of users maintained by Trellix ePO - On-prem. The Trellix ePO - On-prem User Directory cannot be transferred from one Trellix ePO - On-prem server to another and for this reason, system transfer of User Directory users is not supported.

Pre-requisites - Software

For the system transfer and user assignment to be successful:

• the destination server must be a supported version of Trellix ePO - On-prem 5.3.x or higher.

• the source server may be any supported version of Trellix ePO - On-prem.

• the destination Trellix ePO - On-prem server must be running Drive Encryption 7.x.x.

• the systems must be running Drive Encryption 7.x.x.

Pre-requisites - Configuration

For the system transfer and user assignment to be successful:

• the destination server should have all relevant AD servers configured as registered servers.

• if chase referrals is enabled, ensure that all AD servers are reachable.

• the system transfer feature should be enabled on the destination server, using the web-API.

• an appropriate AD search order must be specified if the destination server has more than one LDAP server using the web-API.

• the maximum number of users that can be transferred may be specified through the web-API - if no limit is specified, a default limit is used.

• branch users should be pre-assigned within the destination server.

• Drive Encryption system policy should be appropriately configured in the destination server.

• Drive Encryption user-based policy should be appropriately configured in the destination server.

• appropriate Drive Encryption theme and simple words configuration should be made in the destination server.

• suitable policy-assignment rules should be configured (if applicable).

• any systems that inherit user/group assignments by system tree location should be pre-populated in the destination server, in the correct system tree location.

Reporting

In order to monitor the transfer of systems and detect any issues with the process, a canned query has been provided, that can

Trellix Drive Encryption 7.4.x Client Transfer Migration Guide

5

2 | Introduction

be monitored from within the destination server Trellix ePO - On-prem console. This canned query reports any systems that have failed the Trellix ePO - On-prem system transfer process, along with an initial root cause analysis of the failure.

It is recommended that this query be routinely checked during system transfers. A server task can be configured to automatically email the results of the query at regular intervals, if desired. For more information, please see the Trellix ePO - On-prem product documentation corresponding to your destination server version.

Note that the report uses the standard property collection mechanism of Trellix ePO - On-prem, and as such will require systems to perform an agent-server communication in order to obtain the most up-to-date properties. For this reason, it is common for reports to show inconsistent data due to an expected lag in property collection.

Error handling

In the event that there is an error during the transfer process, the affected system's Drive Encryption service will go into an error state and not perform any further policy enforcement until the service is restarted or the system is restarted. This prevents the destination server becoming overloaded with many systems repeatedly requesting information in the event of a structural configuration issue.

Possible causes of errors during the transfer process are:

• number of users being transferred is greater than the specified maximum.

• users cannot be assigned in the destination server because it cannot be found in the Active Directory.

A suitable error event will be sent up to destination sever to allow administrators to identify affected systems.

In the event of an error, the system can be returned to the control of the source server until the root cause is identified.

For environments using chase referrals, failure of the referral (due to an unreachable AD server) will result in either user assignment failure (if the user cannot be found) or assignment of the user from an AD server lower in the search order (where the user exists in multiple directories).

Scalability

There is a direct correlation between the performance of the client transfer solution and the number of Drive Encryption users assigned to each system.

The number of user assignments that needs to be made by the destination server in a single ASCI is:

numAssignments = numSystemsTransferred x numUsersNeedingAssignment

Equally, the number of user data transfers that need to be made in a single ASCI is:

numDataTransfers = numSystemsTransferred x numUsersPerSystem

Each system will also transfer its encryption and recovery keys during this ASCI, so systems should be transferred in batches.

2 | Introduction

The Trellix ePO - On-prem infrastructure provides a limited bandwidth that could become overwhelmed if too many systems are transferred at once, or the number of users requiring to be assigned to each system in the destination server is excessive.

When enabling the system transfer feature, it's possible to prevent the system transfer from occurring when the number of users that will be assigned to the system during the transfer exceeds a specified limit (configurable maximum number).

In the example given above, if the number of users in List A exceeds the limit (configurable maximum number), then system transfer will be abandoned and a suitable error event sent up to the destination server. Note that the limit applies only to those users that are not currently assigned to the system (either explicitly or through inheritance from a branch) in the destination server when the transfer starts.

Branch assignments of Drive Encryption users within the source server need to be configured manually within the destination server before systems are transferred. If this step is omitted, the system may fail to transfer if it reaches the maximum user assignment limit.

Initiating system transfer

In order to safely transfer systems that have Trellix Drive Encryption installed and activated on them, it is important to keep the system in the source Trellix ePO - On-prem server until the transfer process has been successfully completed. If the transfer process fails, the system may need to be moved back to the source server until the problem is resolved. This cannot be done, if the system is deleted from the source server, as all user assignments and user data may have been deleted.

Important

Note that systems must not be transferred using the Trellix ePO - On-prem system tree Agent → System Transfer, because it deletes the system from the source Trellix ePO - On-prem server.

Systems can be safely transferred by manually deploying the Trellix Agent FramePkg from the destination server to the system. For more information, see the Trellix Agent 5.x.x Product Guide: FAQ: How can I redirect the communication from a Trellix Agent to a new Trellix ePO - On-prem server?

Enable the system transfer feature

Enabling system transfer must be performed using the web-API. An example python script to illustrate how this could be accomplished is included later in this document and is available via Software Manager. This section lists the two new web-APIs included to enable this feature.

2 | Introduction

    eeadmin.listRegisteredServers Lists servers that have been registered with Trellix ePO - On-prem, (optionally) filtered by type. Returns a dictionary containing the ID, type, and registered server name for each of the current registered servers.

2 | Introduction

Trellix Drive Encryption 7.4.x Client Transfer Migration Guide

9

2 | Introduction

2 | Introduction

    eeadmin.enableSystemTransfer Enables/disables system transfer capability. Returns a dictionary that contains the values that have been saved. Omit all parameters to make no changes and list current settings.

Trellix Drive Encryption 7.4.x Client Transfer Migration Guide

3 | Introduction

Handling failures

This chapter explains about recovering systems and troubleshooting methods.

Triage

In the event of a failure, further transfers should be postponed until the cause is determined.

A canned query is provided for detection within the destination server of systems that have failed the transfer. This query can be monitored whilst transferring batches of systems, in order to quickly detect failures.

Any failures will also generate an audit event that will be reported to the destination server and also logged to the Drive Encryption log file on the system.

Recommended investigation

• Check the Trellix ePO - On-prem product client events audit for the system and their details

• Check the Drive Encryption log (MfeEpe.log)

• Check the Trellix ePO - On-prem orion log

• Check the agent handler logs

Once the issue has been resolved, the Drive Encryption service on the system should be restarted in order to kick off the process again; this can also be accomplished by restarting the system.

Troubleshooting

The following are the troubleshooting methods for some of the commonly occurring errors:

User policy not enforced after transfer has completed

This can occur because of one of the following reasons:

• A policy assignment rule has been defined.

• The user was assigned to a branch that the system is a child of, however the system was not known by the destination server at the moment when the user was configured for UBP enforcement.

• At the point when the user was configured for UBP enforcement, the system was not known to the destination server or the user was not assigned to the system.

Resolutions

• Run the DE: Force update for UBP enforcement users from the Server Tasks page in the destination server and wait for

3 | Introduction

the task to complete. Then wake up the system to obtain the latest policies.

• It is possible to use an automatic response to trigger the DE: Force update for UBP enforcement users when {x} number of events have been received, by using the event ID 30090. For more information, see the product documentation for your version of Trellix ePO - On-prem.

Note

{x} must be a level that your Trellix ePO - On-prem server can handle; numbers below 200 could cause scalability issues on both Trellix ePO - On-prem and AD servers due to the number of policies that might need to be recalculated.

User cannot logon to a system that they were assigned to after transfer completes

This can occur because the transferred system user data is sent on the subsequent policy enforcement and the user has already been assigned to another system during that period in the context of the destination server.

In this scenario, the user will be treated as an uninitialized user and the default password could be used (if the user has been configured to use a password token). However, if the default password is used, the latest user data will overwrite any existing user data.

User is prompted to enter a new password

This can occur because the transferred system user has been assigned to another system before the migrated system has sent the user data to destination server and UBP has been configured to 'Do not prompt for default password'.

Recovering systems after a failure

You can recover your system in the following ways:

• Exporting recovery keys — It is still possible to export the recovery keys from the source server by selecting the system and exporting the key or by providing the keycheck value.

• Administrator recovery — The policy of the destination server will not be enforced on the system in a failure case. Administrator recovery is therefore only possible from the source server.

• Repatriation of failed systems — If a system fails the transfer, transfer the system back to the source server - policy enforcement will start again until the problem is identified and solved.