Who is this article for?

This article is intended to help LucidLink Classic account owners who are upgrading their filespace(s) to the new LucidLink using the Upgrade Tool. The Upgrade Tool processes all of your data, users, groups, permissions, settings, and billing; so you can use them with the new LucidLink without having to copy them over manually.  The following video and guide will walk you through the process.

Part of a series on the LucidLink Upgrade Tool.

Getting started

To begin the upgrade process, log in to your account in the new LucidLink using the LucidLink desktop application on MacOS, Windows, or Linux.

If you do not already have an account in the new LucidLink, you'll need to create one to get access to the Upgrade Tool.

You won't be able to start the Upgrade Tool flow without a backup code generated. Please make sure you have one generated before attempting to use the Upgrade Tool.

Once your account has been created and you have logged in, you can choose “Upgrade from Classic” from the center of the dashboard (if you're not a member or owner of any workspaces) or from the user menu at the top right.

Upgrading a filespace requires that you create a new workspace as part of the upgrade process.

If you are logging into the new LucidLink for the first time, ignore the prompt to "create a new workspace."

Disclosures

Next you’ll see some explanation of what's included in the upgrade process. Please read each item carefully before proceeding, as the upgrade process is irreversible once completed.

While the upgrade does preserve your data, users, groups, and permissions, it does not preserve your local settings, snapshots, pins, or share links.

Carefully read the description of changes included in the upgrade process on each page, then click “next."

If you're coming from a filespace prior to v2.2 in LucidLink Classic, the upgrade process will automatically apply our v2.2+ permission model ("fine-grained permissions") to your filespace. As a result, it may be necessary to re-establish links to assets in your applications following the upgrade.

Once you've read over all of the disclosures thoroughly, check the box to acknowledge you understand these changes, and then click “continue to upgrade.”

The new LucidLink is a fundamentally different product from LucidLink Classic. While we're confident that users will benefit from all the new experience has to offer, we encourage you to compare the features of each before making the decision to upgrade.

Logging into the Classic webportal and selecting a filespace

Next, you’ll be prompted to authenticate with the LucidLink Classic web portal. As in the web, you can do this with either username and password or Google auth (every account supports one or the other, but not both). Selecting "Login with Google" will open a web browser for you to authenticate with Google.

After successful authentication, you will see all filespaces in the domain associated with your Classic web portal login. Helpful details are included for each filespace in the list.

Filespaces that are not eligible (suspended, not initialized, errored) cannot be selected. Likewise, filespaces that are already upgraded will be marked accordingly.

Select the filespace you would like to upgrade from the list and then click “continue."

Workspace creation and billing migration

Next, you will enter the name of the new workspace that will contain your upgraded filespaces. If your Classic domain contains several filespaces that you need to upgrade; you won't need to complete this step on subsequent runs, because this step also links your Classic domain and the new LucidLink workspace that you've created. 

To proceed, you'll need to acknowledge the above with a checkbox and then click "Continue". 

Again, this is irreversible once completed (even if you don't complete the rest of the upgrade!); so make sure you're prepared before you continue.

Now that your new workspace has been created, you can pause here if you'd like to complete SSO configuration before importing users and continuing with the rest of the filespace upgrade. This may be preferable if you want to ensure SSO is completely set up and all keys are distributed before performing a cutover.

User mapping

The new LucidLink employs a “global user model,” which means all users are globally unique and only a single user is required to access all of your workspaces and filespaces. The new LucidLink requires that an email address be used as the identity for this user.

To preserve users, groups, and permissions from LucidLink Classic, you'll need to map your Classic usernames to corresponding email addresses for use in the new LucidLink. 

It's not necessary for the user to have first created an account in the new LucidLink. They can do this when they accept the invite in a later step.

Click download CSV to get a file with all of your usernames. This comma separated file can be opened in most spreadsheet software such as Excel, Sheets, or Numbers.

If you prefer to manually invite your teammates later, you can click on “skip user import” This will allow you to upgrade the filespace without users, groups, or permissions.

Next to each username listed in the spreadsheet, enter the email address associated with that user.

If there are any usernames that are no longer needed, you can simply delete that row.

If you're already using email addresses as usernames in LucidLink Classic, you can simply copy and paste all of the usernames into the email address column (most spreadsheet editors also support dragging to copy columns).

Formulas can also make transformation easier.

After you’ve finished adding email addresses to the CSV, save the file and upload it back into the upgrade tool.

If there are duplicate users being migrated from multiple filespaces, their permissions will be merged in the new workspace.

You can also assign multiple Classic usernames to a single email if needed (for instance if you had "service" accounts with permissions you'd like to preserve or consolidate).

Click “continue” to begin the upgrade process.

Filespace upgrade

Next you'll be prompted to confirm by entering the name of the filespace you'd like to upgrade.

The upgrade is now running. You’ll see progress bars for each step of the process.  It’s important to remember to stay connected to the internet throughout the process. If you change your mind or need to cancel for any reason you can click on “abort upgrade."

Cancelling the upgrade will require that you start over from the beginning - you cannot pause and resume the upgrade process at will. It must be completed in a single session.

As the UI indicates, user input is required during the "Prepare filespaces" step, so don't step away just yet.

As mentioned, you'll be prompted to enter the root user password from the Classic filespace near the end of the "Prepare filespaces" step. You won't need to enter a username since it will always be "root" - you just need to supply the root user's password. 

Only the root user is valid for completing the upgrade process. Due to zero knowledge we cannot recover the root user password for you if you've forgotten it.

Reach out to support or your account representative for assistance if this applies to you.

The upgrade will continue. Depending on the size of your filespace, this may take some time. We estimate approximately 1 minute per seventy-five thousand filesystem entries (files and folders). To achieve optimal performance, we recommend using a local machine (as opposed to a cloud virtual machine), with a fast SSD drive attached. Due to our zero-knowledge model, the process is entirely executed on the machine that runs the Upgrade Tool and is heavily write-intensive on the local disk.

Ideally the upgrade is an attended process, but you can step away if needed while the process completes. Just don't exit the app and please disable any power saving features that might cause the system to sleep or enter any reduced power states for the duration.

Inviting and onboarding users

Next, you need to invite your teammates.  To do so, click “copy invite link”.  This one link will be used to invite all of your LucidLink classic users to become members of the new LucidLink workspace.  If you're going to be using Single Sign On (SSO), you can skip the invitation step.

Due to our zero-knowledge security model, LucidLink cannot send the invitations for you, so you’ll need to paste this invitation link into an email or other type of message and send it to your teammates.

If you lose your invite link, you can always access it again by navigating to Workspace > Members > Pending

Once the upgrade is completed, the filespace is available for use immediately. All files can be streamed instantly, again owing to the fact that the data stayed in place.

As one of the many perks of migrating to the new LucidLink, you can now access your content on the web and via iOS and Android (if enabled) in addition to the desktop app.

Users will need to install the appropriate apps to gain access. We recommend planning ahead for the upgrade process - read our full list of recommendations here.

Repeating the process and finishing up

If you have more than one filespace in your domain to upgrade, you can click “Upgrade another filespace” to run through this same process with another filespace.

An indicator at the bottom left of the Upgrade Tool indicates how many filespaces you have remaining in the source domain. Once all filespaces have been upgraded, you'll see a screen at the summary step letting you know the upgrade process is completed. If there are no valid filespaces remaining in a LucidLink Classic account, you'll be unable to start an upgrade with that domain.

Remember that domain to workspace mappings are 1:1, so if you want to migrate another domain, you'll need to create another new workspace to accept its billing details and filespaces.

After you're done

Any upgraded filespaces will remain accessible in LucidLink Classic for 30 days in read-only mode. This includes access to snapshots captured prior to the upgrade. After 30 days, the LucidLink Classic hubs will be decommissioned automatically and the filespace + any snapshots will become inaccessible.

During the upgrade process, a snapshot named "Lucid service - upgrade" is created on each filespace. This snapshot captures the state of the filespace at the time of the upgrade. As with all other snapshots, retaining this snapshot prevents the data represented within it from being permanently deleted from object storage as long as it exists. This additional data counts against your billable storage totals. Once you have successfully upgraded and the source filespace has been cleaned up, you may elect to delete this screenshot to free up the retained data and optimize your storage utilization.

This snapshot cannot be deleted until the Classic filespace has been permanently decommissioned and is no longer accessible.

In case you want to delete this snapshot, go to the "Snapshots" menu of your filespace, click the three-dot menu to the right of the snapshot and select "Delete".

Please reach out if you have any questions

Once the upgrade process starts, there's no going back. Work with your LucidLink representative to develop a game plan that's right for you and your organization.

The Upgrade Tool is designed to allow you and your team to quickly and easily adopt the new LucidLink and take advantage of all its great features. We hope that this guide has helped prepare you for the upgrade process ahead. 

If you still have questions, don’t hesitate to reach out to Support or your Customer Success Account Manager.