Windows: Upgrading Versions <23.242 to the Latest Version

Instructions for systems with managed storage encryption enabled

If you have enabled managed store encryption, and you have not yet changed your encryption from RC4 to AES256:

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. 

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.

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 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.

If you are upgrading to the latest FileCloud version and you are using a custom mongodb.conf

If you are running mongoDB as a service in Windows and updating from a version of FileCloud earlier than 23.242 to the latest version, and you are replacing the provided mongodb.conf with a custom one, it is important that you remove the journal=true setting which is no longer supported.

To remove the command:

1. Open C:\\xampp\mongodb\mongodb.conf.

2. Delete the lines that are highlighted in the image below and save the file.
   

If you are upgrading to the latest version and you are using custom API services

If you are using custom API services, the services may be logged out after the session timeout time (15 minutes by default). To prevent this from happening, in your custom API code, in requests to the FileCloud API, change your user-agent header to contain the string "FileCloud API". This is a one-time change only required when you upgrade from a version prior to 23.242 to the latest version.
Examples:
In PHP script, change:

// Set the custom User-Agent header
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "User-Agent: CustomUserAgent/1.0"
]);

to:

// Set the custom User-Agent header
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "User-Agent: FileCloud API"
]);

In CLI, change:

curl -X GET https://filecloud-domain.com/core/getfilelist -H "User-Agent: CustomUserAgent/1.0"

to:

curl -X GET https://filecloud-domain.com/core/getfilelist -H "User-Agent: FileCloud API"

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. Stop the FileCloud ServerLink client service in secondary nodes.

4. Upgrade the primary node first.

5. Upgrade each secondary node after upgrading the primary node.

6. Start the FileCloud ServerLink client service in secondary nodes. (In HA setups, client service must run only in one of the servers from each secondary node.)

Note: All connected ServerLink nodes, both primary and secondary, must be upgraded to the same ServerLink version before enabling access to the site again.

Correcting the AD mail attribute

Prior to version 23.241, FileCloud always used the AD attribute mail to authenticate AD users, even if the AD mail attribute field in FileCloud specified a different attribute.

This has been fixed. However, if you used an AD attribute other than mail prior to the current version, AD users imported into FileCloud prior to the current version will now receive an error when they try to log in to FileCloud (unless the non-mail attribute always has the same value as the mail attribute). If you have users who may have trouble logging in for this reason, prior to updating, change the AD mail attribute field back to mail.

Upgrade instructions for the FileCloud 23.242 Outlook Add-in 

If you are upgrading FileCloud, and you plan to use the updated FileCloud Outlook Add-in, if you have previously modified the default values for Access-Control-Allow-origin or Access-Control-Allow-Credentials, they may not be set to the values required to run the FileCloud Outlook Add-in. After updating the Outlook Add-in, open .htaccess and make sure these settings have the values indicated below.

To check/replace the htaccess settings:

1. Open the .htacess file:
   Windows:  C:\xampp\htdocs\.htaccess

2. If the following commands are missing or are present, but set to different values, set them as follows:

   Header always set Access-Control-Allow-Origin https://ffol.filecloud.com 
   Header set Access-Control-Allow-Credentials true
   

Configuring SSO after updating from a version older than 23.241

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). If you are upgrading from a version prior to 23.1, upgrading to the latest version 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 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 Windows environments using Solr and Solr+OCR

1. Upgrade FileCloud

2. Upgrade OpenJDK to version 17.

3. Set JAVA_HOME to the new version's path.

4. Log in to the FileCloud admin portal.

5. In the FileCloud Control Panel, and stop and restart Content Search.