Upgrade Notes for FileCloud 23.241 or Later

Version 23.241.x of FileCloud has dropped support for Shibboleth 1.3 and SAML 1.1, and updated SimpleSAML to version 2.x. If you have upgraded to FileCloud 23.241 or later and your FileCloud build uses SSO, follow the instructions below Configuring SSO after updating to 23.241 or later or SSO will not work correctly in your system.

Upgrading to 23.241.x completely disables WebDAV functionality; if your system uses WebDAV, please contact FileCloud Support before upgrading.

New pre-upgrade instructions have been added for systems with managed storage enabled. To avoid losing any data, please review and perform the pre-upgrade process if it applies to you.

Backwards Compatibility Notes

You cannot upgrade Windows and Linux using the Admin Portal.

Beginning with Version 21.1, the files to download when upgrading with the Windows Update Tool have changed. The new files are listed below under Upgrade for Windows and with the full upgrade procedure in the documentation page Upgrade using Update Tool (Windows Only)

Upgrading

As always, make a full backup of your existing installation before upgrading.

If your installation of FileCloud uses admin portal user access restrictions, please see Restricting Access To Admin UI Based On IP Addresses for updated instructions.

Instructions for systems with managed storage encryption enabled

If you have enabled managed store encryption, you must change your storage encryption from RC4, which has been deprecated, to AES-256 prior to FileCloud upgrade. Your file key, a 183-character string used as a password for storage encryption, is stored in encrypted form in the FileCloud database. To change your file key encryption from RC4 to AES-256, use the following pre-upgrade instructions. 

If you are not using managed storage encryption, you do not have to perform this process. 

Pre-upgrade


To change your storage encryption from RC4 to AES-256
:

To view the correct version of the admin portal in the following procedure, either empty your browser cache or view in incognito mode. 
To empty your browser cache, go to development mode, click refresh, and then choose Empty cache and hard reload.

If your system is running in Linux and you are migrating to a new FileCloud server from FileCloud 22.1, go to the section Migrating FileCloud 22.1 with local encryption storage to Ubuntu 22.04 and RHEL 9, below.

  1. If you are running FileCloud versions 22.1 through 23.232.x, skip this step, and go to step 2.
    If you are running a version of FileCloud less than 22.1:
    1. Upgrade FileCloud to 23.232.1.
    2. Activate encrypted storage for your site (or each of your sites) by providing a password or recovery key.
      For help activating encrypted storage, see: Activating Password Protected Storage Encryption - FileCloud Docs - Server.
      To learn more about setting up encryption in FileCloud see Setting up Managed Storage Encryption - FileCloud Docs - Server.

  2. (Begin here for FileCloud Versions 22.1 through 23.232.x)
    Ensure that encrypted storage is activated for your site (or each site you are running in a multitenant environment) by confirming that Memcache is running on your FileCloud server and that each of your sites has the raw file key stored in the Memcache service.
  3. Ensure that any other FileCloud services you use are running.
  4. Take a snapshot of your production server before running the pre-upgrade tool.
    If possible, further safeguard your data by initially performing this pre-upgrade in a staging environment.
  5. Run the pre-upgrade tool:
    • For Linux systems:
      Download the latest version of filecloudcp by running this command:
      curl --location 'repo.filecloudlabs.com/static/fcp/filecloudcp' -o /usr/bin/filecloudcp	
      Set the correct permissions for the file by running:
      chmod 755 /usr/bin/filecloudcp
      Start the pre-upgrade tool by running:
      filecloudcp –fpm
    • For Windows systems: Run upgrade as you would using the instructions on page Upgrade using Update Tool (Windows Only).
  6.  When the pre-upgrade is successfully completed, manually activate storage encryption for your site (or each of your sites in a multi-tenant environment).
    1. During this step, you may optionally enter a new encryption password to encrypt the RAW key stored in AES-256 instead of RC4 (however, the same password may be used).

Troubleshooting encryption pre-upgrades 

PROBLEM:
The pre-upgrade tool returns a STOP result.
This may happen when the Memcache service is turned off or if a site with encrypted storage is inactive, and potentially leads to loss of the raw file key from Memcache and deactivation of encrypted storage.
SOLUTION:
Run the Memcache service to ensure that storage encryption is activated, then run the pre-upgrade tool again.

PROBLEM:
Wrong File Key for Multi-Tenant Environments. For multi-tenant environments, the pre-upgrade tool might retrieve the wrong File Key for sites, leading to data loss.
SOLUTION:
Ensure storage encryption is activated by running the Memcache service. If the wrong File Key is retrieved for multi-tenant environments, decrypt the data, disable encryption, perform the upgrade, and then re-enable encryption.  


PROBLEM:
One inactive website with encrypted storage blocks upgrades on all other websites.
SOLUTION:
Decrypt and disable encryption, then perform a site database backup, and remove the unused site.

PROBLEM: 
Service Provider Licensing Agreement (SPLA) admin lacks options to enable inactive encrypted storage.
SOLUTION:
Ensure you have access to the storage system in SPLA admin settings.


Migrating FileCloud 22.1 with managed storage and encryption enabled to Ubuntu 22.04 or RHEL 9 

Follow one of the options to migrate FileCloud 22.1 to an updated operating system and to upgrade it to 23.241.or later.

Option 1: For customers running with or without FIPS mode: (recommended option): 

  1. Decrypt the files in FileCloud 22.1
  2. Install one of the supported operating systems (Ubuntu 22.04 or RHEL 9).
  3. Install the latest version of FileCloud 23.241 or later on the newly installed operating system.
  4. Migrate FileCloud to the newly installed operating system.
  5. Encrypt the data in FileCloud.

Option 2: For customers running without FIPS mode:
This method does not require decryption.

  1. Perform a FileCloud upgrade to FileCloud 23.232.1, which requires OS upgrades to Ubuntu 22.04 or RHEL 9.x. For this procedure, please Contact FileCloud Support
  2. Follow the upgrade instructions on page Upgrade FileCloud on Linux from Version 23.232 to the Latest FileCloud Version
    Please note that FileCloud Support cannot resolve OS upgrade problems. 
  3. Use the pre-upgrade instructions to upgrade from 23.232.1 to 23.241 or later starting with Step 2. (Begin here for FileCloud Versions 22.1 through 23.232.x).

Upgrade instructions for Linux

Upgrading FileCloud from 23.232.x or lower to latest version

To upgrade FileCloud from 23.232.x to the latest version in Linux see Upgrade FileCloud on Linux from Version 23.232 to the Latest FileCloud Version.

Upgrading FileCloud from 22.1 to Ubuntu 22.04 and RHEL 9

You can either re-install FileCloud or upgrade both FileCloud and your operating system.

Option 1:  Install one of the supported operating systems, then Install the latest version of FileCloud on the newly installed operating system, and then migrate FileCloud to the newly installed operating system. This is the recommended option. 

Option 2:   Perform a FileCloud upgrade which requires OS upgrades to Ubuntu 22.04 or RHEL 9.x, For this procedure, please Contact FileCloud Support
Please note that FileCloud Support cannot resolve OS upgrade problems. 

Upgrading FileCloud from versions lower than 22.1

If you are upgrading from a version of FileCloud lower than 22.1 or from an operating system below Ubuntu 22.04 LTS or RHEL 9, please install one of the supported operating systems, then Install the latest version of FileCloud on the newly installed operating system, and then migrate FileCloud to the newly installed operating system.

Upgrade instructions for Windows

For all upgrades, once upgrade is complete, refresh the browser using CTRL-F5 to clear any prior setup information from the cache.

You can use the Windows Upgrade tool to do a full upgrade.

Windows Update Tool

When you are upgrading to FileCloud 23.241 or later, leave all FileCloud services in the control panel running instead of stopping them all as in upgrades of previous versions.

Beginning with FileCloud 21.1, there are new files to download which are listed in the updated steps 1-3 of the upgrade procedure, below.

  1. Download the FileCloud Windows Update Tool from https://patch.codelathe.com/tonidocloud/live/installer/cloudupdatetool.zip

  2. Extract all files from cloudupdatetool.zip into a folder. 

  3. Download the following files and copy them to the extracted folder (the cloudupdatetool folder)

       Now, go to Upgrade using Update Tool (Windows Only) and proceed from Step 2, #5.


Upgrading systems that use ServerLink

To upgrade systems running ServerLink, the following steps should be taken:

  1. Before upgrade, ensure all ServerLink nodes are fully synced and are at the same state.
  2. Make backups of all nodes as needed
  3. Upgrade the primary node first.
  4. Upgrade each secondary node after upgrading the primary node.
  5. Start up all nodes

Configuring SSO after updating to 23.241 or later

SimpleSAML update

Version 23.241.x of FileCloud has updated SimpleSAML to version 2.x. If your FileCloud build uses SSO, please take the following steps to replace your old configuration files with new ones; otherwise, SSO will not work correctly in your system.

  1. Go to your SimpleSAML config directory.
    Windows: C:xampp\htdocs\thirdparty\simplesaml\config
    Linux: /var/www/html/thirdparty/simplesaml/config
  2. Rename:
    config.php to config.php.bak
    authsources.php 
    to authsources.php.bak
  3. Then rename:
    config.php-[date] to config.php
    authsources.php-[date] to authsources.php
  4. Copy any modifications you made to the original config.php (now config.php.bak) to the current config.php
  5. Copy any modifications you made to the original authsources.php (now authsoruces.php.bak) to the current authsources.php

Alias directive modification

The Alias directive has been modified in 23.241. If you have it written as:

Alias /simplesaml "/xampp/htdocs/thirdparty/simplesaml/thirdparty/www"

change it to:

Alias /simplesaml "/xampp/htdocs/thirdparty/simplesaml/public"

for more information, see SSO Configuration Steps, Step 1. Configure Apache Webserver.

FC Push Service Configuration

In FileCloud version 23.1, a Push service was added to allow clients (in particular, FileCloud Desktop) to receive server-initiated notifications (for example, file upload, share). Upgrading to FileCloud 23.1 or higher on systems running with MongoDB replica set or standalone MongoDB require the push service env file to be updated based on the MongoDB configuration.

To configure the Push service in Linux:

  1. Open and edit the .env file from path: /opt/fcpushservice/

    vi /opt/fcpushservice/.env
  2. Update the MongoDB connection string:

    FCPS_DB_DSN=mongodb://dbuser:passw0rd1@dbserver01,dbserver02,dbserver03:27017
  3. Restart the fcpushservice.

    systemctl restart fcpushservice
To configure the Push service in Windows:

  1. Open the file xampp\pushservice\.env for edit.
  2. Update the MongoDB connection string to:

    FCPS_DB_DSN=mongodb://dbuser:passw0rd1@ dbserver01, dbserver02, dbserver03:27017
  3. Restart the Push service in the FileCloud control panel.

Upgrade environments using Solr and Solr+OCR

Windows

  1. Upgrade FileCloud
  2. Upgrade OpenJDK to version 11.
    1.  Download Open JDK 11.02+9 from https://jdk.java.net/archive/.
    2. Create a new folder in the C: drive.
      (In the example screenshot, jdk-11.0.2 is the name of the new folder.)
    3. Extract the Open JDK file you downloaded into the new folder.
  3. Set JAVA_HOME to the new version's path.

    Setting the path and environment variables will differ depending on the version of Windows you have on your computer. These instructions were designed for Windows 11.

    (warning)  Administrator privileges are required to modify the path and environment variables.

    To set the JAVA_Home path:

    1. Open the Windows Control Panel.
    2. Enter environment variables in the search bar.
    3. Click Edit the system environment variables.

    4. In the System Properties dialog box, click Environment Variables.

      The Environment Variables dialog box opens.
    5. In the System variables box, Click JAVA_HOME, and then click Edit.
      The Edit System Variable dialog box opens.
    6. Change Variable value to the address of the folder you created for jdk, and click OK.
    7. In the Environment Variables dialog box, click OK.
  4. Log in to the FileCloud admin portal.
  5. In the FileCloud Control Panel, and stop and restart Content Search.

Linux

  1. Upgrade FileCloud.
  2. Run:
    filecloudcp --install-solr
  3. If OCR is enabled, run:
    filecloudcp -t
  4. Log in to the FileCloud admin portal.
  5. Restart Solr.
    systemctl restart solr