Any user of the Migration App.
Q: How do I get Migration App?
A: Admins for any Platform Plan domain can enable Migration App in a self-service manner. Click on the application picker menu and select Migration from the drop down. This will display the Migration Landing Page. If Migration App is already fully enabled for your domain, you will see two blue On-Premises Migration buttons. Click either button to access the Migration Dashboard. If you have not yet enabled it, you will see a button labeled Request enablement for my domain. Click this and walk through a simple wizard. Once you have submitted the wizard, any Admin for your domain will now see the blue On-Premises Migration buttons on the Landing Page.
Q: What types of domains can use Migration App?
A: There are various types of Egnyte domains, but Migration App cannot be enabled for all types.
- Trial domains: In general, Migration App should not be used by Trial Domains. Trial domains are ineligible due to the storage limitations imposed by the trial program. If a Trial domain is limited to the standard 20GB storage, any migration job that exceeds this amount will fail. One exception may be for Enterprise Trials, which eliminate the storage limitations.
- Archive domains: Yes.
- Vanity domains: No. An example of a vanity domain is myfiles.companyname.com which is essentially an alias from your standard Egnyte domain companyname.egnyte.com. To use Migration App, you must have it enabled on your standard domain and run all your migrations there.
- FedRAMP Alias domains: Yes. Example: fedramp[mydomain].egnyte.com
- Egnytegov.com domains: No, however it is compatible with "FedRAMP alias domains." So instead of migrating to [mydomain].egnytegov.com, you instead use Migration App to copy data to fedramp[mydomain].egnyte.com
Q: How do I find Migration App once my domain has been granted access?
A: Admins can find Migration under the application picker menu. Select that to view the Migration Landing Page. If your domain has access to Migration App, you will see two blue buttons labeled On-Prem Migration. Click either button to reach your Migration Dashboard.
Although only Admins can access Migration App by default, Power Users may also be granted access by exception. See Enabling Power Users to use Migration App.
Q: Once enabled, does Migration App remain enabled?
Q: Is there anything special I need to do if I was originally using the CMM Agent CLI tool, but now want to use Migration App?
A: Yes, check out this Helpdesk article for an important prerequisite.
Q: What are the firewall requirements for Migration App?
For more detailed setup information for Migration App, see the Product Guide.
Q: What do I need to know before I use Migration App?
A: See Overview of Migration App for everything you need to prepare yourself for success using Migration App.
Q: How can I find my Agent ID?
A: See this Helpdesk article FAQs About the Migration Agent
Q: Why do I need to provide my Windows Login credentials to set up my Agent?
A: Migration App requires information to identify both the Source and the Destination. Your Windows Login defines the Source, so you need both the username and password for an identity that has access to network shares. The Destination is defined by the domain and the Admin’s username.
Q: Is the Agent Setup form case-sensitive?
A: Yes and no. Egnyte username is not case-sensitive. But Windows AD usernames are case-sensitive.
Q: What do I do if my Agent becomes disconnected from the Cloud?
A: See this Helpdesk article Troubleshoot the Migration App Agent.
Q: Does it matter what version of Migration App Agent I have?
A: You should not have to worry about what version you are running. The Agent autonomously updates whenever a new version is available. It will wait to update until after your Agent has finished running any active migration jobs.
Occasionally, you may need to manually update your Agent. If so, ensure no Migration job commands are currently running. After the Agent updates, you will be able to keep running your existing migration jobs as before.
Q: How can I tell what version of the Agent I have running?
A: Navigate to your Migration Dashboard and click on any Agent in the left column. It will expand to provide more details, including the version number.
Q: Can I update the Migration App Agent when a migration job is running?
A: No. You need to be sure no jobs are running before you update the Agent. For more information, see this Helpdesk article.
Q: I had to change my Windows password, and now my Agent is running but doesn't seem to have access to any network shares.
A: If you change the user password for the Windows user associated with the Agent, you will need to change it on the Agent settings as well. You can follow the steps explained in Ensuring Windows Host Machine And Source Are On The Same AD Domain to change your password and restart the Agent.
Q: Can I install more than one Agent on my Windows host machine?
A: No. There's no reason why you'd need to. One Agent is all you need for a single Source, and one Source can support the creation of multiple migration jobs. However, we recommend you run no more than 3-4 migration jobs concurrently.
For more complex migration projects, you can use your Migration Dashboard to manage additional Sources, which would require separate Windows hosts, each with a different Agent installed.
The Migration Dashboard
Q: Why can't I see other Admins' migration jobs on the Migration Dashboard?
A: By design, Migration App aligns each migration job with the individual user who created it. As a result, you can only see the migration Agents and Jobs you created while logged in as a given user. For more complicated migration projects, many customers choose to create a single shared "Migration User," such as "Migration-Admin@domain.egnyte.com." This allows multiple admins to log in with these credentials to share a single Migration Dashboard for visibility into all migration activities.
However, if you want to have visibility into migration activities on your domain by other Admins, you can download the Migration Jobs Listing from the Migration Dashboard. This will provide information about every Agent and every Migration Job active for your domain. See Viewing the Migration Jobs Listing.
Q: How can I clean up my dashboard and remove Agents and Jobs that are no longer needed?
A: See this Helpdesk article.
Q: When would I see more than one Agent on my dashboard?
A: The Migrations Dashboard allows for multiple Agents. However, only one can be installed per Windows host machine, so in most cases you will only have one Agent activated. You would see multiple Agents only when you are using the dashboard to run migrations from multiple Windows host machines. An example might be if you were running migrations from different physical offices. In this case, each host would have their own installed Agent running migrations from different locations to your Egnyte domain.
Q: How do I know what an Error or Status Code means?
A: See this Helpdesk article Migration App Status and Error Codes for a complete listing. This can be helpful in troubleshooting and if you need to request technical support.
Q: Where can I find Migration Reports?
A: On the Details page for any migration job, there’s a blue link in the upper right corner to Download report. Click on that to be redirected to the /Shared/Migrations folder on your Egnyte file server, where the report will be posted. From there, right-click on the CSV file to download it and open it in Excel.
You may also download a Migration Jobs Listing for your domain from the upper right corner of the Migration Dashboard. This will include migration jobs created by all users.
Creating a Migration Job
Q: Can I create a migration job where the Source is a mapped drive letter?
A: Yes. You can create a job where the source is either a mapped drive letter, an absolute path or a UNC path. To determine a UNC path:
- Hold down the Windows key + R, type cmd and click OK.
- In the command window type net use then hit Enter/Return.
- Make a note of the required path, then type Exit, then hit Enter/Return.
Q: Can I create a migration job where the source data is on Azure Cloud?
A: Yes. You just need a Windows VM on Azure, and ensure the data is accessible as a mount point from that Windows VM. There can be some connectivity issues with this type of implementation, so we recommend creating smaller migration jobs and doing an initial proof of concept.
Q: When I create a migration job, how do I specify the Destination?
A: The Destination needs to be a valid Egnyte folder path. The Destination must be specified as /Shared/<filename> or /Private/username/<filename>. Migration App will create the folder named <filename> within the respective root folder. Folder names in the path cannot be empty, contain special characters ( * ? \ < > ), or start or end with a space, symbol or period.
For more information, see Creating a New Migration Job.
Q: I just created a migration job but I'm getting an error “Unable to validate source path.” What should I do?
A: This occurs if the correct permissions for either the Source or the Destination aren’t in place. You need to authenticate the Agent as a User who has AD permissions to read from the Source, and you must also be an Egnyte Admin to access the Destination.
Q: Are there any special considerations for a Windows workstation mapped to a Mac for source data?
A: Yes. We've seen this be successful, when the Mac is assigned a drive letter on a network. This requires the Mac OS be updated to at least High Sierra 10.13.
Q: Can I migrate data from an external drive (flash drive or USB drive) connected to my network, even if I don’t have enough space on the local machine to download the data there first?
A: Yes. If you can map a data source to a letter drive on your AD network and view it from the Windows host machine where your Agent is installed, you can migrate it using Migration App.
What Gets Migrated
Q: Are there any limits to the size of migration jobs with Migration App?
A: Yes. See Maximum Migration Job Size for detailed information.
Q: Does the Migration App migrate empty folders?
A: Yes! By default, you are offered the option to migrate empty folders with every Data Migration and True-Up command. However, you can also specify your preferences using Advanced Options. More information is available in this Helpdesk article.
Q: What do you mean by "Excluded files" and "Unsupported files and folders"?
A: See Understanding the Scan Results for more information.
Q: Is Migration App case-sensitive?
A: Yes. See this article about canonically equivalent files for more information.
Q: Migration App failed to migrate some folders in the job. Why would that be?
A: There can be multiple reasons for folders not migrating.
If folders are empty and you didn't opt in for migrating empty folders, they will not be migrated.
Another reason might be that the user who registered the Agent doesn’t have the necessary permissions to view those folders.
There are also limitations to what Migration App can migrate. More information may be found in this Helpdesk article Understanding the Scan Results.
One edge case is when you have a folder on the Source that contains only unsupported files. In this case, none of the files will be migrated, nor will the folder be created on the Destination. And since this folder is not empty on the Source, it will not be created as part of the empty folder migration step. So, in the end, this folder will always be missing in Destination. There is no way presently to migrate it.
Q: Migration App failed to migrate some files. Why is that?
A: One common reason for files failing to migrate is that they may be currently in use. That's why we recommend running several True-Ups after the initial Data Migration and before the final Cutover. Remember that for the final Cutover, all users must be "hands-off" the original Source until cutting over to Egnyte.
More information may be found in the Helpdesk article Understanding the Scan Results.
Q: If I have folders with more than 50K immediate children, can they still be migrated? Is 50K a hard limit or just a suggested limit for performance reasons?
A: A maximum of 50K immediate child objects is a fixed limit of the Egnyte platform, not of Migration App. You will need to break your folders down into smaller subsets to use Egnyte.
Q: Can I use the Migration App to migrate additional content into folders on my Egnyte domain that already contains data?
A: Yes, you can. In fact, that's an excellent use case for Migration App. To do this without duplicating data, you need to create individual migration jobs for each top-level folder under Shared or Private. You also need to be sure you enable Confluence Mode for these jobs, which will automatically opt out of syncing deletes. This will ensure no data is inadvertently deleted.
Q: Can I use Migration App to migrate from a Flash drive?
A: Yes. A flash drive (USB drive) works the same way as any local drive. It can be a bit slower when compared to an internal SSD, but you should still be able to create and operate jobs sourcing the connected drive.
Q: What do I do if the Migration Report indicates that files cannot be migrated because they have a future timestamp?
A: This is an infrequent occurrence and may be due to the data having been transferred from one system to another prior to attempting migration. Regardless of the cause, there is nothing Migration App or Egnyte can do to resolve this. However, this can be mitigated in one of two ways:
- Changing the date/timestamp on files manually. Obviously this is only viable if there is a very small number of files showing future timestamps.
- Running a script to change it on the source. Simply do an online search for "script to change future timestamp on files." This provides resources offering guidance on writing and running a script on your source. Once this is done, migrate normally.
True-Ups or Syncing
Q: Is a True-Up the same thing as a Sync?
Q: How do I run a True-Up? What’s the difference between Migrating Data and running a True-Up?A: See Understanding Data Migration and True-Ups.
Q: If I run a True-up, does it create duplicates of what was already copied previously?
A: No. Running a True-Up simply updates the Destination to match the current state of the Source.
Q: What happens if I run a True-Up but a user has updated a file on Egnyte?
A: We generally discourage any data changes on Egnyte until the entire Migration is completed. But if a user does change a file on Egnyte and you subsequently run a True-Up on the data, Migration App will just create a new version of the file. Here’s how it works.
- Migration Job “ABC” migrates File X to Egnyte on August 1.
- A user changes File X on Egnyte on August 2.
- On August 3, a True-up of Migration Job “ABC" runs. Migration App will recognize that File X is different. So it will again copy the August 1 version of the file, but this will appear as a new version of File X on Egnyte. This means the user will be able to access both versions on Egnyte.
Q: How do I run the Sanitize command?
A: Sanitize is not a standalone (atomic) command. It is an optional component of the meta commands Migrate Data and True-Up Data. By default, when you initiate a data migration command, you are provided a modal where you select whether you want to sanitize on the Source or On-the-Fly. More information may be found in the Helpdesk article Understanding Sanitization Options in Migration App.
Q: Does Migration App change long file path names when we run the Sanitize command?
A: No, it does not change file names or path names that are too long. These files and pathnames are merely flagged during Scan and can’t be migrated unless the user makes the necessary changes on the Source. For more information about Egnyte path limits, see the Helpdesk article Unsupported Characters and File Types.
Q: What does the Sanitize function do?
A: Sanitizing changes any unsupported characters in filenames to an underscore. This can be done in one of two ways:
- Sanitizing on the Source, where the unsupported characters are changed on the Source before migrating.
- Sanitizing On-the-Fly, where the characters are changed during migration and nothing is changed on the Source.
For more information about this, see Helpdesk article.
Q: How does Migration App migrate permissions?
Q: How long does it take to migrate permissions?
A: It can take a fair amount of time to migrate permissions. They are applied at approximately one per second.
Q: How do NTFS permissions translate to Egnyte permissions?
Q: Can I modify how permissions are mapped with Migration App?
A: No, not currently, although this is on our roadmap.
Q: Does Migration App migrate permissions at both the folder level and the file level?
A: Not exactly. Migration App migrates permissions for folders. The files contained therein inherit the parent folder's permissions.
Q: Are there any limitations for Migration App to migrate permissions?
A: Yes. All Users and Groups must already exist on Egnyte in order for permissions to migrate successfully. If any Users or Groups are missing, the Migration Report will provide insights into that.
Q: What happens if I run a permissions migration, but a needed User or Group has not yet been created on Egnyte?
A: The Migration Report provides a worksheet for both Missing Users and Missing Groups. Once you have created those Users and Groups on Egnyte, you may run Permissions Migration again. See Simulating and Migrating Permissions in Migration App.
Q: Can I “sync” or True-Up permissions with Migration App?
A: Not exactly. In Migration App, Permissions Migration is an all-or-nothing command. So running it multiple times just replaces whatever was created previously. We recommend you run Permissions migration at the very end of a migration job, right before you cut over all your users from using the Source to using Egnyte.
Q: Why doesn't Migration App provide any progress information in the Status Bar while permissions are migrating?
A: Permissions migration involves three distinct steps, and each step takes some time. During the first and second steps no information is communicated through the Migration Dashboard to the user because it is all happening at a database level. Only once the permissions are being applied to the files on Egnyte does the progress bar show any movement.
Q: If I migrate content into Shared, but it has different permissions on the Source than those set on the Destination (Egnyte), which permissions prevail?
A: This is controlled by the Egnyte cloud platform at the domain level. It defaults to "keep source permissions" but can be changed in Settings.
Q: How does a Permissions Migration Simulation work?
A: Think of it as a dry-run to help you identify gaps where you still need to create users or groups on Egnyte in order for the permissions migration to be successful. See Simulating and Migrating Permissions in Migration App.
Speed, Bandwidth, and Throughput
Q: How can I estimate how long a migration job will take?
A: You can first check out the speed test for your domain. Go to https://<domainname>.egnyte.com/speed-test/ (replacing <domainname> with your domain).
Keep in mind there are a lot of factors at play, but this will at least give you a baseline. If you’re reading from a network share, that will also impact your upload speed. For more information, see How Long Will it Take to Upload, Backup, or Download my Files?
Q: Why does the estimated time to complete a migration job keep changing on the dashboard?
A: For every file, Migration App does a metadata operation on the background, so the ETA is a function of the number of objects in the migration (folders and files combined.) For a total payload of similar size, if it comprises lots of small files, it takes longer than if the migration comprised a few larger files. As a given Migration job works through the files, the estimated time will continue to change based on the size of the current files being moved.
Q: How many migrations can run concurrently from the same Agent?
A: This depends on the capacity of the host machine where the Agent is running. Each migration job takes around 250 MB of memory. Depending on your host machine CPU/memory, you may run three or four concurrent migration jobs. We don’t recommend running more than four jobs at one time. The limitation here is not the Migration App itself but rather the Egnyte system back end.
Q. Is there a minimum bandwidth requirement for the Migration App?
A: No. migration jobs will see higher throughput the more bandwidth you have. But high latency/low bandwidth is one of the use cases for Migration App. These jobs will take more time.
Q: What to do about improving upload speeds for migration jobs? Is it possible to specify additional threads for the Migration App to increase the throughput?
A: Yes. To do this, you must first have Advanced Mode enabled for your domain. Then you can use the Throughput or Threads features in Advanced Options, located on your Migration Details page.
Advanced Options and Advanced Mode
Q: What is the difference between Advanced Mode and Advanced Options?
A: Advanced Options are a set of feature controls available for all migration jobs. To access them go to the Migration Details page and click on the arrow next to Advanced Options in the left column.
Advanced Mode, however, is a setting that can be enabled for a domain that will give the Migration Operator several additional, more technical controls. We recommend this be used only by seasoned users of Migration App. See Advanced Mode in Migration App.
Q: What can I control with Advanced Options?
A: Advanced Options provides controls for the following functionality:
- Migrating Empty Folders
- Changing the Skip Scan Period
- Excluding File Types
- Confluence Mode
- Scheduling Migration Jobs
- Symbolic Links
- Opt Out of Syncing Deletes
- Log Management
Q: What is Advanced Mode?
A: Advanced Mode is a setting that allows the Migration Operator to undertake several more complex actions in Migration App. It is not enabled by default, so it must be first enabled for the domain, and then more options become available. Advanced Mode features are very technical and can have a major impact on your host machine and migration job. Accordingly, we only recommend Advanced Mode for the most experienced Migration Operators. See Advanced Mode in Migration App.
Q: How do I get Advanced Mode enabled for my domain?
A: Submit a ticket to firstname.lastname@example.org requesting enablement.
Q: What features are available with Advanced Mode?
A: Advanced Mode enables the following features:
- Increasing the threads (transfers and checkers) for a job to improve performance.
- Controlling bandwidth throughput for a job..
- Customizing the Agent Configuration
- Using Exclusion Rules - See Advanced Mode in Migration App.
Q: How do you change the threads for improved performance?
A: This requires Advanced Mode to be enabled for your domain. See Advanced Mode in Migration App.
Q: How do you change the bandwidth throughput for reduced strain on my network?
A: This requires Advanced Mode be enabled for your domain. See Advanced Mode in Migration App.
Q: How do you modify the Agent Configuration file?
A: This requires Advanced Mode be enabled for your domain. See Advanced Mode in Migration App.
Q: How do you control advanced exclusion rules?
A: This requires Advanced Mode be enabled for your domain. See Advanced Mode in Migration App.
Q: What if the credentials to register the Agent won't allow me to access the network share Source?
A: You must ensure the Windows host machine is on the same AD domain as the network share resources. Check out this Helpdesk article Ensuring Windows Host Machine and Source Are on the Same AD Domain.
Q: What if a migration job hangs?
A: Check out this Helpdesk article What if a Migration Job Hangs?
Q: What if the Agent Registration hangs?
A: See this Helpdesk article Troubleshooting the Migration App Agent
Q: What if I’m unable to execute any commands?
A: Refer to this Helpdesk article What if I Am Unable to Execute Any Commands in Migration App?
Q: How do I verify that all my data migrated successfully?
A: There are a couple of ways to verify this: The Job Report and the Job Logs.
The Migration Job Report
- From the Migration Dashboard click the three dots next to the migration job and select Download the Job Report. Alternatively, from the Details page, click Download the Job Report in the upper right corner. Either link will take you to the folder for the migration job on your Egnyte domain inside the Migrations folder under Shared. Download the report to open and view it in Excel.
- From the Job Report you can view a list of items that were not migrated by selecting the Exceptions register. This will list all files and folders that were not migrated and the reason they were excluded. On the Data Migration register or True-Up register, you’ll find any files that failed to migrate due to an error. Everything else should have migrated successfully.
If the Job Report doesn’t provide a satisfactory explanation or if you want to validate checksums, you can also drill down into the Job Logs.
The Job Logs
From the same Migrations folder on your Egnyte domain where you found the Job Report, you’ll find a zip file. Download and click to expand. Inside this you’ll find a folder labeled status. Look for a file within this named success_[JOB ID]. This includes the following information for every item in your migration job:
- Source Path
- Destination Path
- Request ID
- Timestamp for the Operation
- Source Checksum
- Destination Checksum
To learn more about Migration App logs, read the article.
Q: How do I know why a file or folder was deleted during a True-Up?
A: You can confirm this from the Job Logs that are stored on the local machine where you have the Migration App Agent installed.
Depending on how you’re logged into Agent, you will find the logs in one of two places.
If you are logged in as the Local System, go to:
If you are logged in as the Local User, go to:
Open the egnyte-agent folder and you will find a folder for each migration job labeled with the Migration ID.
Click to open the scan folder. For every command executed for this job, you will see multiple CSV files. Every file is appended with “_[JOB ID]_[time/date stamp]_[Agent version].”
- cmmagent file – Created whenever a scan is run. May be eliminated in the future as it does not provide any additional information.
- scan file – Also generated for every command. It provides a complete list of all files and folders, including their path name. If IsDir is TRUE, the object is a folder. Each line item includes file size and last modified time.
- empty_folder file – This file is only created when you opt in to migrate empty folders as part of the command. It lists all empty folders identified on the source.
- diff- file – This file is only generated as part of a True-Up. It provides a list of all files to be deleted, and why.
- diff+ file – Also only generated as part of a True-Up. It provides a list of all files to be added.
The diff- file will provide specific information about each file and folder that was deleted during True-Up. Keep in mind that if you don’t want to Sync Deletes, you can disable that feature in Advanced Options. To learn more about Migration App logs, read the article.
Q: What if I can't open the migration report because it is corrupted?
A: While this is not a common occurrence, Excel files can become corrupted. See this article on how/why an Excel file might be corrupted, and some ways to fix them. In most cases, after fixing the file you should be able to reopen it normally.
Q: Can any Egnyte User use Migration App?
A: By default, only Administrators can use Migration App. Power Users can be granted access by exception, but this has several prerequisites. See Enabling Power Users to use Migration App.
Q: Can Migration App be limited to be available to only certain Admin users on a domain?
A: No. Currently, Migration App is enabled for the entire domain. All Admins can see Migration App, and if you make an exception for Power Users, all Power Users can see Migration App.
Q: Can any Administrator monitor migration jobs created by another Administrator?
A: No. Migration jobs are tied to the User/Domain. This becomes the key to each job and therefore only a given User can see their own Agents and Migration Jobs in the dashboard. However, any user can download the Migration Jobs List which details all jobs created by all users.
Q: If I need to stop a migration for some reason, can I restart it later? I don’t want to be using all the bandwidth during the day when it may impact other users doing their work.
A Yes. You can stop and restart a migration job at any time. However, any time you restart a migration job, it needs to do a complete scan of both the source and the destination. This allows it to identify what, if any, data has already been migrated. Actual movement of the data begins where it left off previously. Alternatively, you may wish to consider Controlling Bandwidth for your migration job, which is a feature that requires Advanced Mode be enabled for your domain.
Q: If I need to restart a migration job, what do I need to do?
A: Return to the Migration Dashboard, click on Details for the migration job, and then click Migrate Data (or True-Up Data). It can take a while for the system to determine where it left off, but it will not duplicate content and it will proceed to completion.
Q: Where can I find my migration job logs?
A: It depends on how you’re logged into the Agent.
If you’re logged in as the Local System:
If you are logged in as the Local User:
Q: Is there a way to view checksums for my migrated files?
A: Yes. They are included in your migration job log files. Find the logs for a migration ID (see previous question), then unzip the folder. Open the folder named status. Open the latest CSV file starting with success_[migration ID] and you can see the source and destination checksums for all files migrated.
Q: What if I have a feature request?
A: If you have feature suggestions or requests, feel free to submit them here, and make sure you mention Migration App in the text.
For more complex requests that would benefit from providing screenshots or other attachments, you may submit them to email@example.com. Be sure to include Migration App in the email title. Our Support team will push your comments to the Product team for consideration.
Q: Is there a way to get a quick question answered?
A: You can always submit a support ticket to firstname.lastname@example.org.