-
Title
Installing the Mac OS migration agent -
Description
Installing the Mac OS migration agent -
Resolution
PST Flight Deck supports migration of files from Mac OS workstations. To support such migrations, the Migration Agent (MA) must be deployed on Mac. This document provides guidance on how to install and set up a migration agent on a Mac workstation. And it explains what steps must be executed on a PST Flight Deck server to make it work.
Note: The PST Flight Deck Migration Agent is compatible with macOS El Capitan 10.11 to Mojave 10.14. Catalina 10.15 and newer require the new Mac Agent installer available in PST Flight Deck 7.2.0.191125 and later.Installation
Installation media for a Mac OS migration agent can be requested from Quadrotech.
Follow these steps to install the migration agent.- Double-click on the installation package and follow the prompts.
- You will be prompted to provide Administrator credentials. Enter Administrator credentials to complete the installation.
Installation is now complete.
You should now see the Quadrotech icon in menu bar:
Click on the icon to see options related to the Mac OS migration agent:
Click Show Log to check logs. A Console opens with com.gladwev.flightdec.log, which is the log for the Mac OS migration agent.Setup of destination for the migration agent – setting the PST Flight Deck server (apiuri)
Unlike the Windows version of the migration agent, where the destination is set during the installation process, with Mac OS workstations, it must be done after installation. This can be easily done via this command:
- defaults write com.gladwev.flightdeck apiuri http://YourFDServerName/PSTFlightDeckWS/MacClient.svc
- restart the application FlightDeck Mac Agent:
- if you can see the Quadrotech icon in menu bar, choose Exit.
- if you can’t see it in menu bar, start native the Mac OS application Activity Monitor and search for “FlightDeck Mac Agent”. Select it and quit using the X button.
- Start it again by double click on FlightDeck Mac Agent in Application
Settings needed for the Mac OS migration agent to work in the PST Flight Deck Admin Console
When the migration agent is installed on a Mac OS workstation and the PST Flight Deck core address is set to “apiuri”, you can see in the Administration Console how the Mac OS migration agent presents itself and how to troubleshoot basic issues.
License
You must request Mac OS workstation licenses to be part of PST Flight Deck licensing. The About window shows how many Mac licenses are available. Take a look:
You can see which Mac OS workstations have licenses via Settings > Mac OS Migration Agent > User Licenses button. Take a look:
In order for the Mac OS migration agent to work, you must have a valid registration key.
If you don’t have a valid registration key, you’ll see this message in the migration agent’s logs:
|info|1|MacClient|GetWorkItems : WorkHandler is not initialized, product not registered.Configuration settings
Similar to the Windows migration agent, the Mac OS migration agent can be customized to meet customer needs. All settings for the Mac OS migration agent are in Settings > Mac OS Migration Agent.
Use the Path Excludes and Search Paths field to indicate what should be scanned and what should be excluded.Show/Hide PST Flight Deck icon in Mac OS agent menu bar
If you want to show/hide the PST Flight Deck icon from the Mac OS menu/task bar, follow these steps:
- Select Mac OS Migration Agent from the left menu bar.
- Select Edit Xml in the top menu bar.
- In the Config window, locate this line: true
- Change the line to: false
- Save your changes.
Here’s how it looks:
Troubleshooting on the PST Flight Deck Admin Console
This section can be used to help troubleshoot issues.
Checking to see if the Mac OS migration agent is reaching the PST Flight Deck core
Mac OS workstations should be listed in Settings > Computers. To view them, in the Computer Type column, filter by Mac OS Computer. If you can’t see you Mac OS workstation, go back to the workstation and check:- if you are able ping your PST Flight Deck core server
- if you are able to reach the PST Flight Deck webservice (http://YourFDServerName/PSTFlightDeckWS/MacClient.svc) in a web browser, you will see a screen similar to this:
- if logs on the Mac OS workstation show that you have a valid license (see above for more information)
Mac OS migration agent should report Outlook profile to PST Flight Deck core
To see if the migration agent is reporting to the PST Flight Deck core:
- In core, go to Manage > Files.
- Add the File Type column and filter for Mac Profile 2016 or 2013.
This is the basic identity that must be met before any processing can occur.
When the profile does not appear after some time, try restarting the Mac OS migration agent.
Note that the Path is different for Mac OS files, starting with MAC Workstation followed by : and then ~/ or ~//. Please be aware that this ~ is not equivalent to the “current user” shortcut used in Mac OS workstations. Rather, it indicates in PST Flight Deck that files are from a different file system.Logs
Logs can be accessed from menu in Task Bar, by choosing Show Log option. This will open log file in Console.
If you need to access log file on you file system, logs are stored in a file com.gladwev.flightdeck.log. Location of that file:- Library/Logs/com.gladwev.flightdeck.log
User from Mac OS in Manage > Users
When a Mac OS migration agent reports files for a Mac OS user, it uses the username of the Mac OS user. In many cases, this is not an Active Directory account. To be able to migrate files from a Mac OS workstation to a target (for example, Office 365 cloud), the Mac OS user must be matched with an Active Directory account. This is explained in the next section.
Mac OS users can be identified by User Type = Mac OS user on the Manage > Users screen.User matching
Mac OS users are often not Active Directory users. To be able to migrate files from a Mac OS user/workstation to a target, this account must be matched with an Active Directory account.
Be aware that a user with the type Mac OS user should NOT be enabled. If you try to enable it, you will see the following warning:
Matching can be done in two ways:Automatically
PST Flight Deck can uniquely and reliably match a Mac OS user with an Active Directory account. In such case, no action is required. The Mac OS user is “blended” with an Active Directory account. The original Mac OS user will not be visible anymore and all files for the “blended” user will appear there (there can be both Windows and Mac OS files under one user).
Manually
When there are circumstances preventing PST Flight Deck from doing automatic matching, it must be done manually. For example:
- There might be multiple Outlook profiles on a Mac OS workstation
- The Mac OS user’s name might not match any names in Active Directory
- The Mac OS user’s name might match more than one Active Directory account.
- And so forth
Go to Manage > Events to see information about unsuccessful matching. For example:
Manual matching
PST Flight Deck offers a wizard that can be used to manually match Mac OS users and Active Directory accounts.
You can find it by going to Settings > Mac OS Migration Agent > Manage users. Take a look:
Step 1: The wizard shows only users with the type Mac OS user if they have an uploaded Outlook profile. If the Outlook profile is not yet uploaded you won’t see the Mac OS user here.
Note: The following filter is preset and can’t be deleted:
Step 2: In the AD Users section, select the Active Directory account to which it should be matched.
Step 3: If you are OK with your selection, click Confirm.
The Mac OS user is now “blended” with an Active Directory account and you’ll not be able to find it on the Manage > User screen with the original Mac OS username. Mac OS files now appear under the matched Active Directory account instead.
Uninstalling and cleaning the Mac OS migration agent
When the Mac OS migration agent is not needed anymore or must be replaced with a newer version, you can uninstall the older version and remove all records related to it.
Uninstalling the Mac OS migration agent is simple. To do it, right-click on the application and choose Move to Trash (shown below).
The Mac OS migration agent stores some of its settings in the Mac OS “defaults” mechanism. When the migration agent is removed/uninstalled these settings are left intact. This could cause confusion when installing newer version of the migration agent.
There are two locations on the Mac OS system where migration agent files are stored: global and local (user related). Installation in administrative/root locations are not likely, but could occur. Therefore, check these locations when you’re cleaning the Mac OS migration agent. For global settings and files, an administrative/root account is required.User (local)
Defaults
To check default Mac OS migration agent settings, use this command:
- defaults read com.gladwev.flightdeck
If you want to read only a specific parameter and you know its name use it in “”:
- defaults read com.gladwev.flightdeck “apiuri”
To delete values from defaults and completely remove migration agent records from the system, use these commands:
- defaults delete com.gladwev.flightedeck “apiuri” – this deletes just apiuri
- defaults delete com.gladwev.flightdeck – this deletes all settings for the Mac OS migration agent
Logs
Logs are stored in a file named com.gladwev.flightdeck.log
- Library/Logs/com.gladwev.flightdeck.log
If you want to delete log, remove it via:
- rm Library/Logs/com.gladwev.flightdeck.log
Data
The Mac OS migration agent stores its data in Library/Application Support/com.gladwev.flightdeck. Remove this directory and its content to wipe all migration history from the Mac OS workstation. For example:
- rm -r ~/Library/Application\ Support/com.gladwev.flightdeck/
Global (root/admin)
Some information might be stored globally. To wipe this data, you’ll need root/administrative access to be able to execute elevated commands via sudo
Defaults
- sudo defaults delete /Library/Preference/com.gladwev.flightdeck “apiuri” – use this command if you want to delete just apiuri
- sudo defaults delete /Library/Preference/com.gladwev.flightdeck – use this command delete all settings for Mac OS migration agent
Logs
This log is not usual, but just in case check this location for log:
- /Library/Logs/com.gladwev.flightdeck.log
And, if the log exists, remove it via:
- sudo rm /Library/Logs/com.gladwev.flightdeck.log
Note
- Please be aware of difference between /Library (absolute path) and Library (user path relative to logged user also known as ~ path in *nix systems) directories.
- There is a difference between global (root) and user (local) access to resources.
- In Mac OS ~ is translated to /Users/CurrentUser.
- \ in a path is “escape character” for space.
- You can enclose a path with special characters like space into ” “
Please be careful with sudo and rm commands as they can harm your Mac OS installation if they’re used improperly.
