This article offers a checklist to help administrators of LucidLink Classic filespaces prepare the upgrade to the new LucidLink using the LucidLink Upgrade Tool.

Confirm you’re eligible

The first step is to confirm your eligibility.

• Review the feature matrix. If an essential workflow isn’t yet supported, postpone the upgrade until it appears in the matrix.

• If you are redirected to the page below, contact your Customer Success representative or reach out to upgrade@lucidlink.com to discuss upgrade eligibility.

Gather the required details

1. Owner email for the new workspace: The address used to run the Upgrade Tool becomes the workspace owner, so be sure it’s active and monitored.

2. LucidLink Classic web portal credentials: You’ll sign in to the Classic web portal in the Upgrade tool to select the filespace to upgrade. This may either be a password or a linked Google account.

3. Root account password: The Upgrade Tool will prompt you for the root‐user password of the filespace before beginning the upgrade. We operate under a zero-knowledge policy and cannot recover this password. If you don’t know it, please contact your Customer Success representative.

4. Networking information: If your network requires exemptions to access LucidLink resources, you'll want to review this article and coordinate obtaining those details for the new LucidLink in advance.

Select the right machine to run the Upgrade Tool

The Upgrade Tool preserves our zero-knowledge model, which means that all the Upgrade will be performed on the machine running the tool, which is heavily write-intensive on the local disk. We recommend:

• using a local physical (as opposed to a cloud machine or a virtual workstation) to achieve optimal performance. Virtual/cloud disks will typically perform significantly slower than a local disk.

• the local drive is SSD or NVME (C: drive or "Macintosh HD" drive), with high random read/write speeds.

• the CPU is relatively recent (not more than 4 years old, the higher specs the better)

• this workstation has enough RAM available (at least 8GB)

• power saving features must be disabled (low power, sleep mode, locked screen, etc)

Configure your network exemptions (if needed)

If you network requires exemptions to access LucidLink resources, you will need to add those exclusions prior to your upgrade.

More specifically, the following outbound connections on port 443 must be enabled to ensure a smooth upgrade:

• *.fs.lucidlink.com. The Upgrade Tool will provision a new hub as part of the upgrade process, therefore the use of wildcard is strongly recommended. After the upgrade, you can restrict the rule to your specific hub FQDN. To obtain it, use the lucid status to get your filespace UUID. The hub's FQDN should look like the following: 
  0a00a00a-bb11-22cc-333d-4e44e44e4444.fs.lucidlink.com
• LucidLink discovery service - DNS Record discovery-service.lucidlink.com.
  Whitelisting by the FQDN is recommended, as the IP address of this service can change.
• Object storage endpoint(s) TCP/IP typically port 443 standard HTTPS traffic. This endpoint should already be excluded as it is already used in LucidLink Classic.
• LucidLink web service - api.lucidlink.com.

Additionally, we use certificates signed by our internal certificate authority (CA). Some firewalls do Secure Sockets Layer (SSL) decryption (aka Deep Packet Inspection (DPI) or SSL Certificate Inspection). This is interpreted as a man-in-the-middle attack, by injecting their own CA in the trusted store and using it to impersonate the accessed service.

In highly secure or isolated network environments, administrators may need to allow outbound HTTP connections on port 80 to *.amazontrust.com for proper SSL certificate validation. The SSL certificate for https://app.lucidlink.com is issued by Amazon Trust Services and is configured to perform OCSP (Online Certificate Status Protocol) revocation checks via HTTP to Amazon's certificate authority endpoints.  If outbound HTTP traffic on port 80 is blocked, the OCSP revocation check will fail, resulting in an unsuccessful SSL certificate validation and preventing the establishment of secure connections to app.lucidlink.com. To maintain proper certificate validation functionality, environments with restricted outbound HTTP traffic should ensure that port 80 connections to *.amazontrust.com are allowed.

More information can be found in this article.

Configure Single Sign-On (if needed)

If Single Sign-On (SSO) is a requirement for your organization, we suggest starting the Upgrade process until the Step 4 "Connect Users" of the Upgrade Tool. You can find the detailed steps in this article.

At step 4, your LucidLink Classic domain will be migrated to a new LucidLink workspace, but the actual filespaces are not upgraded yet. This allows you to configure SSO on this workspace. You can also prepare the user mapping CSV file ahead of the upgrade window.

A complete series of articles on setting up SSO in the new LucidLink can be found here.

Distribute the app ahead of time

To ensure a seamless transition, we recommend installing the LucidLink app on user machines ahead of the upgrade process. The LucidLink Classic and new LucidLink apps can coexist side-by-side. While web access is available, users will need the new LucidLink app in place in order to access content on the desktop.

We recommend that the LucidLink Classic application be left in place to facilitate access to snapshots if needed in the short-to-medium term. However, we recommend having users disconnect and forget filespaces in the app to avoid having the filespace auto-mount in Classic and conflict with the mount point in the new LucidLink (which will be the same).

Plan downtime in advance

We strongly suggest performing the upgrade during scheduled downtime. The Classic filespace will remain accessible in read-only mode during the upgrade, but any users who remain connected when the process begins could lose unsaved changes due to being unable to write to the filespace.

The Upgrade Tool should allow most filespaces to be upgraded in less than 30 minutes. Larger filespaces might take more time. At the end of the upgrade process, all users should be able to join the new LucidLink environment and connect to the upgraded filespace with the new LucidLink application.

Prepare your machine

Ideally the upgrade is an attended process. As long as the upgrade is in progress, please do not exit the app and disable any power saving features that might cause the system to sleep or enter any reduced power states for the duration.

Inform your users

Clear, proactive communication with end-users is key to a smooth transition. Tell them:

• When the maintenance window begins and ends

• That data will be read-only during and after the upgrade

• When they can reconnect with the new LucidLink app

A sample email template pre-upgrade is available here.

Post-upgrade, you can use this other email template.

After the filespace(s) have been upgraded, the users will need to switch to the new LucidLink application. Please refer to this article for more information.

All set?

If you’ve completed every step above, you’re ready.  Please refer to this article for step-by-step instructions on how to use the Upgrade Tool.