Section 9. Settings. Binary Tree 9.2

Section 9. Settings

The Settings screen allows you to define the settings used when the device Cutover process is started, create

ReACL Profiles, and add custom Menu Actions.

9.1 Migration Options

To add migration options:

1. Click the Migration Options tab.

2. Click the Add button. The Migration Options window appears.

SMART ACTIVE DIRECTORY MIGRATOR 9.2 USER GUIDE 54

3. Enter values in the following fields: o Option Name - the name to identify the options (for example, "10 Second Reboot Delay") o Domain Join Delay - the delay (in seconds) before joining the domain o Reboot Delay - the delay (in seconds) before rebooting

If set to any value other than zero (0), the user will receive a pop-up notification informing them that the workstation will be rebooted when the cutover is performed. If set to zero, no notification will appear. o Recycle Bin - select how to handle the Recycle Bin during cutover, either Empty or Don't Empty

Users may get an error message that their Recycle Bin has been corrupted after migration if the Recycle

Bin is not empty. See Troubleshooting for more information about this issue. o Target OU - the target OU where the devices will be created. If you leave this field blank, the devices will default to the Computers container.

4. Check Join to Existing Device if you want the device to join to the existing target computer during cutover.

5. Click Save. The migration options are added to the list.

SMART ACTIVE DIRECTORY MIGRATOR 9.2 USER GUIDE 55

9.2 Cutover Credentials

The specified credentials must be able to join and disjoin a computer from the specified domain and well as disable a computer in the specified domain. A trust between the source and target domain is not required.

To add cutover credentials:

1. Click Cutover Credentials tab.

2. Click the Add button. The Cutover Credentials window appears.

3. Enter values in the following fields: o Name - the name to identify the cutover credentials (for example, "DomA to DomB Admins") o Source Domain FQDN - the domain FQDN of the source in source.domain.dom format o Source Username - the username to access the source domain in domain\username or UPN

([email protected]) format o Source Password - the password to access the source domain o Target Domain FQDN - the domain FQDN of the target in target.domain.dom format o Target Username - the username to access the target domain in domain\username or

UPN ([email protected]) format o Target Password - the password to access the target domain

4. Click Save. The cutover credentials are added to the list.

9.3 Network Profiles

To add network profiles:

1. Click the Network Profiles tab.

SMART ACTIVE DIRECTORY MIGRATOR 9.2 USER GUIDE 56

2. Click the Add button. The Network Profiles window appears.

3. Enter values in the following fields: o Profile Name - the name to identify the network profile o Obtain DNS server address automatically? - options include No Change, Manually Assign, or Use DHCP

If you manually assign DNS settings, be sure that the DNS server(s) that you include here can resolve the

ADM Agent SRV record. o Preferred DNS Server - the preferred DNS server o Alternate DNS Server - the alternate DNS server o Append primary and connection specific DNS suffixes - options include No Change, Obtain from NIC, or

Manually Assign. o DNS Suffixes - Enabled if Manually Assign is selected to the Append primary and connection specific

DNS suffixes option. The list of DNS suffixes. Enter each suffix and then press Enter. o DNS Suffix for this Connection - the DNS suffix once cutover is complete o Register the connection's addresses in DNS - options include No Change, No, or Yes o Use this connection's DNS suffix in DNS registration - Enabled if Yes is selected to the Register the connection's addresses in DNS option, select No Change, Don't register manual DNS suffix, or Register

manual DNS suffix. o Preferred WINS Server - the preferred WINS server

SMART ACTIVE DIRECTORY MIGRATOR 9.2 USER GUIDE 57

o Alternate Wins Server - the alternate WINS server

4. Click Save. The network profile is added to the list.

9.4 Device ReACL Profiles

The default Device ReACL profile is used if a different profile is not defined and set on the devices. The default Device

ReACL profile can be edited.

To add Device ReACL profiles:

1. Click the Device ReACL Profiles tab.

2. Click the Add button. The Device ReACL Profile window appears.

3. In the Profile Name field, enter a name to identify the Device ReACL Profile.

4. Under the Basic tab:

SMART ACTIVE DIRECTORY MIGRATOR 9.2 USER GUIDE 58

 In the Blacklist Folders box, enter folder paths that will not be included in the ReACL process. Wild card characters (* and ?) can be used when specifying blacklist folders. Separate the paths by pressing Enter.

By default, the following folders are blacklisted:

 \Windows

 \WINNT

 \I386

 \Windows\I386

 \Program Files

 \PROGRAM FILES (x86)

 \MSOCACHE

 \System Volume Information

 \Recycler

 \$RECYCLE.BIN

 \CONFIG.MSI

 \RECOVERY

 \OEM

 \Quarantine

 \BOOT

 Select an option from the Logging Level drop-down list. Options include Info (default) and Debug.

5. Click the Advanced tab.

SMART ACTIVE DIRECTORY MIGRATOR 9.2 USER GUIDE 59

The Advanced tab allows you a more granular selection of the components to be included or excluded from the

ReACL process. Select the components to be included by checking the desired items.

We recommend that you leave the Windows Services Accounts box UNCHECKED. A change in the ACL of the services accounts of the target may have an impact on the applications currently running. Although the ReACL process can usually be rolled back in case of issues, there could be a temporary disruption in service until resolved.

If you select Roaming Profiles, users must be logged out of their roaming profiles during the ReACL process.

6. If the Local/Files folders box is selected on the left, normally all files and folders are included in the ReACL process. If you prefer to provide a specific list, enter the list in the Only ReACL These Local Folders box.

Separate each entry by pressing Enter. You may use just a file path using backslashes, or provide an exact drive letter. If you provide a drive letter, the ReACL is limited to that exact path.

SMART ACTIVE DIRECTORY MIGRATOR 9.2 USER GUIDE 60

Note that if you choose to list folders here, these are the ONLY folders that will be included in the ReACL process. (The exception is if you check the User Profiles box: those Profiles will always be included automatically in addition to your list.)

7. Select an option from the Elevate Failure Action drop-down list to choose the action that should be taken if any part of the ReACL process encounters errors.

In order to successfully adjust permissions, AD Migrator must create a process with a security token that has been assigned additional permissions. The token is said to have elevated rights/permissions. If this process fails, it is likely that the ReACL will be largely unsuccessful in updating the operating system for use by target user accounts.

 The default is Terminate ReACL, meaning the ReACL process for that device is stopped as soon as an error occurs. This is a time-saving option. The ReACL process is reported as Failed in the Devices View. A device cannot be Cutover if the ReACL process reports as Failed. This is the recommended setting.

 If you choose Error, the entire process will attempt to complete when an Elevate Failure error is encountered, but the process will still be reported as Failed. This selection may take significantly more time than Terminate ReACL, as the entire process will attempt to finish before reporting as Failed.

 If you choose Warn, a warning entry will be logged, however the process will be reported as Successful.

This choice allows experienced migration architects to analyze the logs and choose to Cutover anyway based on their analysis of the results.

 If you choose Info, an info entry will be logged, however the process will be reported as Successful. This choice allows experienced migration architects to analyze the logs and choose to Cutover anyway based on their analysis of the results. We suggest choosing Warn over Info as this will make the entries easier to locate in the log.

8. Select an option from the Invalid/Duplicate Target Profile Action drop-down list to choose the action that should be taken when an invalid or duplicate profile exists in the target.

 The default is Terminate ReACL, meaning the ReACL process for that device is stopped as soon as an error occurs. This is a time-saving option. The ReACL process is reported as Failed in the Devices View. A device cannot be Cutover if the ReACL process reports as Failed. This is the recommended setting.

 If you choose Error, the entire process will attempt to complete when an Elevate Failure error is encountered, but the process will still be reported as Failed. This selection may take significantly more time than Terminate ReACL, as the entire process will attempt to finish before reporting as Failed.

 If you choose Warn, a warning entry will be logged, however the process will be reported as Successful.

This choice allows experienced migration architects to analyze the logs and choose to Cutover anyway based on their analysis of the results.

 If you choose Info, an info entry will be logged, however the process will be reported as Successful. This choice allows experienced migration architects to analyze the logs and choose to Cutover anyway based on their analysis of the results. We suggest choosing Warn over Info as this will make the entries easier to locate in the log.

9. Select an option from the Add Rollback Metadata drop-down list.

AD Migrator inserts a "breadcrumb” during the ReACL process to allow seamless rollback of the ReACL process if needed. You can control the insertion of these breadcrumbs (which are removed during the

Cleanup process) if desired, here.

SMART ACTIVE DIRECTORY MIGRATOR 9.2 USER GUIDE 61

 The default is Always and does not affect performance. We recommend this setting. This is the only setting where the changes performed by the ReACL process can be rolled back, or undone, in all scenarios.

 If you choose Only If Ambiguous, metadata will only be included when the rollback settings would be ambiguous. Only If Ambiguous results in the addition of fewer breadcrumbs, preserving usage for times when it may be impossible to determine the original file or folder permissions. This would occur, for example, when users have accounts in multiple domains that will be consolidated into a single domain.

Note that Only If Ambiguous guarantees a ReACL can be rolled back to the original state only when the file system permissions remained unchanged. Modification of ACLs on the file system could create a state where a rollback cannot complete with 100% success. To ensure the ability for a ReACL Rollback in all scenarios, Always should be selected.

 If you are an experienced migration architect, you may choose Never to never include metadata.

If this is selected, a complete rollback may not be possible.

10. Check the Simulation Only (No Actual Changes) box to simulate the results of the ReACL process without actually making any changes to the ACL. Visit the logs/reports to determine any potential issues and correct them before an actual ReACL process. You might use this to create a Device ReACL Profile specifically for testing purposes.

11. Click Save. The Device ReACL Profile is added to the list.

 Click the Restore Defaults button to reset the profile values back to the default settings.

9.5 NAS ReACL Profiles

The default NAS ReACL profile is used if a different profile is not defined and set on the NAS devices. The default NAS

ReACL profile can be edited.

To add NAS ReACL profiles:

1. Click the NAS ReACL Profiles tab.

2. Click the Add button. The NAS ReACL Profile window appears.

SMART ACTIVE DIRECTORY MIGRATOR 9.2 USER GUIDE 62

3. In the Profile Name field, enter a name to identify the NAS ReACL Profile.

4. Under the Basic tab:

 In the Blacklist Folders box, enter folder paths that will not be included in the ReACL process. Wild card characters (* and ?) can be used when specifying blacklist folders. Separate the paths by pressing Enter.

By default, the following folders are blacklisted:

 \Windows

 \WINNT

 \I386

 \Windows\I386

 \Program Files

 \PROGRAM FILES (x86)

 \MSOCACHE

 \System Volume Information

 \Recycler

 \$RECYCLE.BIN

SMART ACTIVE DIRECTORY MIGRATOR 9.2 USER GUIDE 63

 \CONFIG.MSI

 \RECOVERY

 \OEM

 \Quarantine

 \BOOT

 Select an option from the Logging Level drop-down list. Options include Info (default) and Debug.

5. Click the Advanced tab.

The Advanced tab allows you a more granular selection of the components to be included or excluded from the

ReACL process. Select the components to be included by checking the desired items.

6. Enter the network errors that will trigger a retry in the Network Error Retry List field. By default errors 53 and

64 will trigger a retry.

SMART ACTIVE DIRECTORY MIGRATOR 9.2 USER GUIDE 64

7. Enter the number of retries to attempt in the Network Error Retry Count field. The default retry count is 10 retries.

8. Enter the number of seconds between network error retries in the Network Error Retry Interval Seconds field.

The default interval is 1 second.

9. Select an option from the Elevate Failure Action drop-down list to choose the action that should be taken if any part of the ReACL process encounters errors.

In order to successfully adjust permissions, AD Migrator must create a process with a security token that has been assigned additional permissions. The token is said to have elevated rights/permissions. If this process fails, it is likely that the ReACL will be largely unsuccessful in updating the operating system for use by target user accounts.

 The default is Terminate ReACL, meaning the ReACL process for that device is stopped as soon as an error occurs. This is a time-saving option. The ReACL process is reported as Failed in the Devices View. A device cannot be Cutover if the ReACL process reports as Failed. This is the recommended setting.

 If you choose Error, the entire process will attempt to complete when an Elevate Failure error is encountered, but the process will still be reported as Failed. This selection may take significantly more time than Terminate ReACL, as the entire process will attempt to finish before reporting as Failed.

 If you choose Warn, a warning entry will be logged, however the process will be reported as Successful.

This choice allows experienced migration architects to analyze the logs and choose to Cutover anyway based on their analysis of the results.

 If you choose Info, an info entry will be logged, however the process will be reported as Successful. This choice allows experienced migration architects to analyze the logs and choose to Cutover anyway based on their analysis of the results. We suggest choosing Warn over Info as this will make the entries easier to locate in the log.

10. Select an option from the Add Rollback Metadata drop-down list.

AD Migrator inserts a "breadcrumb” during the ReACL process to allow seamless rollback of the ReACL process if needed. You can control the insertion of these breadcrumbs (which are removed during the Cleanup process) if desired, here.

 The default is Always and does not affect performance. We recommend this setting. This is the only setting where the changes performed by the ReACL process can be rolled back, or undone, in all scenarios.

 If you choose Only If Ambiguous, metadata will only be included when the rollback settings would be ambiguous. Only If Ambiguous results in the addition of fewer breadcrumbs, preserving usage for times when it may be impossible to determine the original file or folder permissions. This would occur, for example, when users have accounts in multiple domains that will be consolidated into a single domain.

Note that Only If Ambiguous guarantees a ReACL can be rolled back to the original state only when the file system permissions remained unchanged. Modification of ACLs on the file system could create a state where a rollback cannot complete with 100% success. To ensure the ability for a ReACL Rollback in all scenarios, Always should be selected.

 If you are an experienced migration architect, you may choose Never to never include metadata.

If this is selected, a complete rollback may not be possible.

SMART ACTIVE DIRECTORY MIGRATOR 9.2 USER GUIDE 65

11. Check the Simulation Only (No Actual Changes) box to simulate the results of the ReACL process without actually making any changes to the ACL. Visit the logs/reports to determine any potential issues and correct them before an actual ReACL process. You might use this to create a Device ReACL Profile specifically for testing purposes.

12. Click Save. The NAS ReACL Profile is added to the list.

 Click the Restore Defaults button to reset the profile values back to the default settings.

9.6 Menu Actions

Menu Selections and Menu Actions

New menu selections that appear as a right-click option on Devices or NAS screens can be created in the Menu Actions tab. Menu selections are a sequence of menu actions to complete a process.

The Menu Selection area will allow you to create a new right-click job menu for devices or NAS shares. Existing or new

Menu Action entries should be dragged over to the desired Menu Selection item to complete the custom job process.

The Menu Action area will allow you to create the action(s) that will be downloaded and executed against devices or

NAS shares. You can associate a single action or multiple actions with a Menu Selection object by dragging each Menu

Action item over to the desired Menu Selection.

It is important to note that system menu selections and actions can only be viewed or copied, they are not editable.

Adding or copying a Menu Action

To add or copy a menu action: Above the Menu Action table, click Add or select an existing menu action and click

Copy (or right-click and select Copy). Check Show System to view and select an existing system menu action.

SMART ACTIVE DIRECTORY MIGRATOR 9.2 USER GUIDE 66

 Menu Action Name (Required): Enter a name for the menu action. The Menu Action Name cannot begin with

"BT-" which is used to identify system menu actions.

 Menu Action Type (Required): Select one of the options from the drop-down list.

 PowerShell Script: Allows you to define a PowerShell script for the process on the Command and

Rollback tabs. Global Variables can be added and used in the script.

 Command Line: Allows you to define a Command line for the process on the Command and Rollback tabs. Global Variables can be added and used in the command line.

 Download File: Downloads a file to the predefined Downloads folder.

 Description: Enter a description for the menu action.

SMART ACTIVE DIRECTORY MIGRATOR 9.2 USER GUIDE 67

 General tab: Mark or unmark the following checkboxes and enter the following options if adding or copying a

PowerShell Script or Command Line:

 Automatic Rollback: if checked, automatic rollback is added to the menu action.

 Requires Cutover Credentials: if checked, the script or command line includes the

$CutoverCredentials_XXXXX parameters.

 Requires Network Profile: if checked, the script or command line includes the $NetworkProfile_XXXXX parameters.

 Requires Migration Options: if checked, the script or command line includes the

$MigrationOption_XXXXX parameters.

 Requires Global Variables: if checked, the script or command line includes the Global Variables.

 Timeout (Seconds): For PowerShell Script or Command Line, enter the number of seconds the process will be attempted before timing out.

 Retry Count: For PowerShell Script or Command Line, enter the number of times the process will be retried.

 Update Interval (Seconds): For PowerShell Script or Command Line, enter the number of seconds between process runs.

 Command tab: Enter a PowerShell scrip to command line. If creating a PowerShell Script, click Starter Script to populate the entry box with the basic framework of a script. Enter or edit the command line or PowerShell

Script. Text is required.

 Rollback tab: Enter a PowerShell scrip to command line. If creating a PowerShell Script, click Starter Script to populate the entry box with the basic framework of a script. Enter or edit the command line or PowerShell

Script. Text is required.

 Download tab: Enter the following options if adding or copying a Download File menu action. When a new download job is created for a managed workstation, the specified file that is stored on the SMART AD Migrator server (c:\Program files\Binary Tree\ADMigrator\Downloads\) will be downloaded to c:\Program files\Binary

Tree\ADMigrator Agent\Downloads\ on the workstation’s local disk.

 File Name (required): The file name. Based on the File Location for Download Jobs used during installation The File Name cannot contain invalid file characters and cannot use reserved file names: map.usr, map.gg, ReACL-config.json.

 Target Location: The target location of the download job. The Target Location cannot contain invalid file characters and cannot use reserved file names: map.usr, map.gg, ReACL-config.json.

 Retry Count: For PowerShell Script or Command Line, enter the number of times the process will be retried.

 Update Interval (Seconds): For PowerShell Script or Command Line, enter the number of seconds between process runs.

 Timeout (Seconds): For PowerShell Script or Command Line, enter the number of seconds the process will be attempted before timing out.

The local download folder on an AD Migrator managed machine will be secured with permissions only for the

BUILTIN\Administrators group.

SMART ACTIVE DIRECTORY MIGRATOR 9.2 USER GUIDE 68

If rights other than BUILTIN\Administrators are required then the administrator will need to make a change on the local downloads folder (c:\Program files\Binary Tree\ADMigrator Agent\Downloads\) on the Agent machine.

Adding or copying a Menu Selection

To add or copy a menu selection: above the Menu Selection table, click Add or select an existing menu selection and click Copy (or right-click and select Copy). Check Show System to view and select an existing system menu selection.

Cover adding menu actions to menu selections (drag and drop), expand, collapse, sequence.

 Menu Selection Name (Required): Enter a name for the menu selection. The Menu Action Name must be unique.

 Display Name: Enter the name that appears in the right-click menu on the Devices or NAS screen.

 Object Type: Select one of the options from the drop-down list.

 Device: The menu selection will appear in the right-click menu on the Devices screen.

 NAS: The menu selection will appear in the right-click menu on the NAS screen.

SMART ACTIVE DIRECTORY MIGRATOR 9.2 USER GUIDE 69

 Activity: Select one of the options from the drop-down list. The Activity determines what validations are applicable to the job, and which status columns are updated when the job runs. for example, a custom menu selection with the ReACL activity, it will have the same validations as the system ReACL menu selection.

 Discovery: Gathers properties from the device.

 ReACL: Updates device domain user profiles for use by the matching target user after cutover.

 ReACLRollback: Rolls back all changes made by the ReACL process.

 ReACLShare: Updates the NAS’s domain user profiles for use by the matching target user after cutover.

 ReACLRollbackShare: Rolls back all changes made by the ReACL process.

 Cutover: Moves a device from the source domain to the new target domain.

 Cleanup: Removes the Source SIDs after the Cutover process completes.

 CleanupShare: Removes the Source SIDs after the Cutover process completes.

 ExplicitRollback: Rejoins a device back to the source domain.

 UploadLogs: Uploads log files from the AD Migrator Device Agent to the AD Migrator Web Server using

Microsoft BITS.

 Other (default): An activity not related to any system activity. No predefined validations are applicable.

By default, new menu selections are assigned as Other.

 Menu Selection Type: This option is not editable. System types are read-only. User types can be edited.

 Description: Enter a description for the menu action.

Adding Menu Actions to Menu Selections

Drag and drop system or custom menu actions from the Menu Action list to the menu selection in the Menu Selection list. Menu actions are listed in the order in which they will be executed. Drag and drop menu actions to reorder them.

Menu Actions can be viewed, copied, or removed by clicking the selecting the menu action and clicking the appropriate button or by right-clicking and selecting an option from the menu.

Activating Menu Selections

Only menu selections marked as Active will appear in the right-click menus. Click the Deactivate or Activate button to change the active status of the menu selection. Inactive menu selections can be displayed in the table by marking the

Show Inactive check box. You may want to create a new menu selection, activate it, and then deactivate the system menu selection.

SMART ACTIVE DIRECTORY MIGRATOR 9.2 USER GUIDE 70

9.7 Custom Menu Action Example

Scenario: The administrator wants to download the Get-DiskSpace.ps1 file on selected workstations.

Steps:

1. Copy the Get-DiskSpace.ps1 file in the file location for download jobs selected during the installation of

SMART AD Migrator, c:\Program files\Binary Tree\ADMigrator\Downloads\ by default.

2. Under the Menu Actions tab in Settings, add a menu action.

3. Select the "Download File" Menu Action Type and enter the File Name. The full path to the file should not be entered.

SMART ACTIVE DIRECTORY MIGRATOR 9.2 USER GUIDE 71

4. Add a menu selection. The Display Name is how the option will appear in the right-click menu. Select the

"Device" Object Type so the menu option will appear on the Devices screen.

5. Drop and drag the new menu action to under the new menu selection and ensure the menu selection is active.

The menu selection can be expanded to view the associated menu action.

6. On the Devices screen, select the devices and then select the new "Get Disk Space" option from the right-click menu. When the new download job is run successfully against a managed machine, the Get-DiskSpace.ps1 file will reside locally on disk at c:\Program files (x86)\Binary Tree\ADMigrator Agent\Downloads.

9.8 Global Variables

Global variables can be defined and be used across multiple scripts when defining menu actions. For example, you may add a global variable to add the current date to multiple scripts. Global variables will appear when selecting a starter script when creating a Menu Action if the Requires Global Variables option is selected.

SMART ACTIVE DIRECTORY MIGRATOR 9.2 USER GUIDE 72

Adding a Global Variable

To add a Global Variable click Add under the Global Variables tab.

 Variable Name (Required): Enter a name for the global variable. The name must contain alphanumeric and underscores only.

 Variable Value (Required): The value of the global variable. Check the Encrypted box to encrypt the value in the database and hide the variable value in the interface.

SMART ACTIVE DIRECTORY MIGRATOR 9.2 USER GUIDE 73