Document toolboxDocument toolbox

Upgrade notes (Instructions for upgrading to a new version)

Owned by Pavel Novák
Last updated: Mar 06, 2024
10 min read

Contents

General instructions

Regardless of the application version from and to which the update or upgrade is proceeding, the following rules and recommendations apply.

Basic rules

  • Regular updates and upgrades are recommended. Especially when a new major version is released.

  • It is not recommended to skip major version upgrades and then later perform an upgrade through multiple major versions. Nonetheless if this happens, it is necessary to go through all the specific steps for these versions and perform those in ascending version order, see below.

  • It is recommended to perform a backup before an update or upgrade, for example in the form of a VM snapshot, or another appropriate way in which the app is being backed up. In case of an unexpected problem it should be then possible to revert back, using the backup.

Upgrade versus update

Until the version 2.0.6 there was only the update, which always performed an update of the application to the latest released version. Since the version 2.0.6 (including) the process was split in two different steps: update and upgrade.

Update

The update of the application performs an update to the latest minor version in the current version branch (same major version), for example from 2.0.6 to 2.0.8 or from 2.1.1 to 2.1.5. It will no longer do an upgrade between major versions (version branches), for example from 2.0.x to 2.1.x. (This is now true even for older versions, so for example executing update in the version 2.0.1 will just update to the latest 2.0.x and will not jump to next major version 2.1.x or further.)

Upgrade

The upgrade of the application performs an upgrade to a new major version branch, if (and only if) one is available. So for example upgrade will perform a transition from the current version 2.0.x to the last version 2.1.x. If a new major version branch does not exist, the upgrade will do nothing. It is therefore not possible to use the upgrade to update the app to a new minor version.

How to combine

Perform common regular updates of the application using the update. If a new major version branch is released (eg. 2.1.0), then to stay up to date it is necessary to perform an upgrade. After that just do regular updates again to update to next minor versions in the current branch.

Mandatory steps

To update the SOFiE application (to the latest minor version in the current major version branch) run the following command from the command line:

sofie update

This command will automatically perform:

  • backup of the application database

  • download and install the rpm packages with the new version

  • perform a migration of the database structures (schema update)

  • restart of the SOFiE application services

To upgrade the SOFiE application (to the latest version in the latest major version branch) run the following command from the command line:

sofie upgrade

This command will perform an upgrade to a new major version branch, if one exists, and then run an update. If a new major version branch does not exist, nothing is done, not even the update.

Next the version specific steps must be performed for all versions through and up to which the upgrade went through. See the details for each version below.

Optional, but recommended, steps

Before and after the update or upgrade it is recommended to check the current version and status of the application using the following commands:

# lists the status of services, should be active (running) for all sofie status # lists the current version, to find out from and to which version the upgrade goes sofie version

Besides updating or upgrading the SOFiE application itself, it is also recommended to perform an upgrade of the operating system, which in the RHEL based systems can be done using the command:

Then it is recommended to restart the server, so it can be verified, that after all the updates and upgrades the system and the application will start up correctly when rebooted:

Finally we check, that the application is working as it should. For example by performing an application test by sending a test package to a user and checking that it arrived and that the user can download it. From the administrator’s point of view we check, that all the configured scans for the package were performed and that the audit log does not contain any errors.

Specific instructions for particular versions

Especially when upgrading to a new major version of the application (e.g. from 1.3.x to 1.4.x), it often happens, that the automatic upgrade process cannot perform all the necessary steps and some steps must be done manually (typically modifying the nginx configuration).

Furthermore, when introducing new features or changes, a conservative approach is usually chosen, so that whenever possible, the upgrade does not introduce changes in the behavior of the application. But that also means, that after the upgrade the new features can be disabled and inactive, and to use them, the configuration must be modified.

Version 2.3.0

Necessary manual upgrade steps

If we want to use the new “Content Disarm and Reconstruction (CDR)“ module, it needs to be installed first according to the following instructions: https://wikisonpo.atlassian.net/wiki/spaces/SPEN/pages/899153928/Installation+manual#Installation-of-the-CDR-module-(optional)

The version 2.3 contains new or modified features. The application administrator should, after performing the upgrade, go through the following settings and consider if and how he wants to use these features:

  • Settings → API Tokens → for individual tokens:

    • Allowed IP ranges

  • Settings → Configuration → Security:

    • new section: Access Restrictions, including:

      • Access Restrictions - IP Filter

      • Access restrictions - reverse record lookup

      • Access restrictions - country

      • Access restrictions - User-Agent header

  • Settings → Configuration → Data Encryption:

    • Key encryption keys (KEK)

      • new recommended key type: HPKE

  • Settings → Configuration → Users:

    • Default settings for new users, new permissions:

      • Set package as persistent

      • Persistent account

  • Settings → Detection Settings:

    • CDR (Content Disarm and Reconstruction)

      • new integrated engine for converting compatible content into a safe form

    • Avast, Trellix

      • newly supported antiviruses

  • Settings → ADFS:

    • new attribute: Directory (tenant) ID

      • no need to change after upgrade to work as before, for ADFS it should be “adfs”

    • newly displayed: Redirect URI

  • Settings → OpenID Connect:

    • an entirely new section allowing integration with OIDC user sources and logins (including Azure AD or Google)

Version 2.2.0

Necessary manual upgrade steps

No manual steps necessary.

The version 2.2 contains new or modified features. Also the structure of the Settings → Configuration menu has undergone serious overhaul. The application administrator should, after performing the upgrade, go through the following settings and consider if and how he wants to use these features:

  • Settings → Users → for individual users:

    • User’s email aliases

    • Set approvers

  • Settings → Configuration → Basic:

    • Configuration management - Configuration export

  • Settings → Configuration → Packages → General:

    • Users can use the briefcase

    • Users can create cooperative packages

  • Settings → Configuration → Packages → Expiration:

    • Shredded packages

      • Automatically delete metadata about shredded packages

      • Expiration of shredded packages' metadata

  • Settings → Configuration → Packages → Access control:

    • Closed environment

      • IP ranges of the closed environment

      • Allow closed → closed transfer

      • Allow closed → open transfer

      • Allow open → closed transfer

      • Allow open → open transfer

      • Allow upload of packages from the closed environment

      • Allow upload of packages from an open environment

  • Settings → Configuration → Packages → Approval of sending:

    • Preferred approver

    • A user can choose his approvers

    • An approver can access all packages that require approval

  • Settings → Configuration → Users:

    • Default settings for new users, new permissions:

      • Use the briefcase

      • Access all packages that require approval

      • Select the approver of packages to be sent

      • Access to detailed check results

      • Create cooperative packages

    • Access detailed results of file checks

      • Logged in users

      • Anonymous users

  • Settings → Configuration → Logging:

    • Retention of audit logs

      • Automatically delete old audit logs

      • Delete audit logs older than

  • Settings → Templates:

    • Modified some existing default templates.

  • Settings → Detection settings:

    • MIME

      • Maximum number of stored records of detected objects

Version 2.1.0

Necessary manual upgrade steps

Since this version the structure of the nginx configuration was substantially modified and also the update and upgrade process was improved in such a way, that in most cases no manual intervention should be necessary. For this improved automation to work correctly, it is required that the installation adheres to the instructions from the installation manual, including:

  • The installation should be done on a dedicated server only for this purpose. Especially it should not contain any manual modifications to the nginx configuration. If it does contain such manual modifications, those will be overwritten during the upgrade to the version 2.1 and the administrator will have to manually fix it or do again.

  • If a custom own SSL/TLS certificate for HTTPS is used, it is expected it will be in the default path mentioned in the installation manual. If another path for the key/certificate was used, the same thing as above in the case of custom nginx modifications applies (will be overwritten and will need manual fix).

The upgrade specifically overwrites the files /etc/nginx/conf.d/default.conf and /etc/nginx/nginx.conf. But it creates a backup of the original files before overwriting them, which look like this:

The version 2.1 contains new or modified features. The application administrator should, after performing the upgrade, go through the following settings and consider if and how he wants to enable and use the new features:

  • Settings → Configuration → Basic settings:

    • Allowed languages for administrators

    • Allowed languages for users

  • Settings → Configuration → Security:

    • new section: Password rules for packages, including:

      • Mandatory package password - not logged in user

      • Mandatory package password - logged in user

    • Login and authorization lifetime:

      • Validity period of one access to a package with a limited number of accesses

  • new section: Settings → Configuration → Security limits, including:

    • section Limit authentication attempts

    • section Limit password reset requests

    • section Limit attempts to access a password protected package

    • section Limit attempts to access a password protected request

    • section Limit attempts to access a non-existent package

    • section Packages with a limited number of accesses

  • Settings → Configuration → Notifications:

    • new section: Approval of sent packages

    • System notifications

      • Notify when the detection engine's quota is exceeded

  • Settings → Configuration → Appearance:

    • new section: Display the terms of use

  • Settings → Configuration → User settings:

    • Default settings for new users, new permissions:

      • Do not enforce a multifactor authentication

      • Approve sending of packages

      • Send packages without additional approval

      • Send packages to yourself

      • Download files from own sent packages

    • new section: Multifactor authentication:

      • Require multifactor authentication for local users

      • Require multifactor authentication for AD users

      • Require multifactor authentication for ADFS users

    • new section: User restrictions by IP ranges

    • new section: Settings for sent packages, including:

      • Users can send packages to themselves

      • Users can download files from their own sent packages

      • Users can send packages without approval

      • Allow access to packages being approved without requiring their password

  • Settings → E-mail templates renamed to Templates:

    • Modified some existing default templates.

    • Created new templates: DETECTION_ENGINE_QUOTA_EXCEEDED, EMAIL_TEMPLATE_CSS, EMAIL_TEMPLATE_PREFIX, EMAIL_TEMPLATE_SUFFIX, PACKAGE_APPROVE_REQUEST, SEND_PACKAGE_APPROVED, SEND_PACKAGE_DISAPPROVED, TERMS_OF_USE.

Version 2.0.3

Necessary manual upgrade steps

  • Edit the file /etc/nginx/proxy.conf and add the following line to the end:

After this change it is necessary to restart or reload nginx:

Version 2.0.0

Necessary manual upgrade steps

Particularly because of the changed behavior, where the downloaded files are no longer served directly by nginx, but by the SOFiE application itself, the nginx configuration must be changed in the following way:

  • Delete the files:

    • /etc/nginx/download-auth.conf

    • /etc/nginx/download.conf

  • Modify the file: /etc/nginx/conf.d/default.conf

    • Delete the sections:

    • In their place add the following new sections:

  • Create a new file: /etc/nginx/proxy.conf with the following contents:

After those changes it is necessary to restart or reload nginx:

The version 2.0 contains a lot of new or modified features. The application administrator should, after performing the upgrade, go through the following settings and consider if and how he wants to enable and use the new features:

  • Settings → Configuration → Basic settings:

    • Allow adding of files to a sent package

    • Allow deleting of files from a sent package

  • Settings → Configuration → Security:

    • Separated password rules for administrators and users, including new feature:

      • Forbid leaked passwords usage

    • Login and authorization lifetime

  • Settings → Configuration → Data encryption:

    • whole new section with configuration for a new functionality

  • Settings → Configuration → Data integrity:

    • whole new section with configuration for a new functionality

  • Settings → Configuration → Logging:

    • The language of syslog records (determined by the default language before)

  • Settings → Configuration → E-mail:

    • A Primary and optionally a secondary language (determined by the default language before)

  • Settings → Configuration → Notifications:

    • new section System notifications

  • Settings → Configuration → User settings:

    • new user permission “Encrypt outgoing packages with a password“

    • new feature “Disable inactive users“

    • new feature “Delete inactive users“

  • Settings → Administrators → add/edit an administrator:

    • new administrator permissions for the new package encryption feature

  • Settings → Users → user permissions:

    • new user permission for the new package encryption feature

  • Settings → Users → add/edit a user:

    • User’s preferred language - affects e-mails sent to the user (determined by the default language before)

    • Temporary user feature - enables an automatic account deletion after the selected date

  • Settings → E-mail templates:

    • Modified some existing default templates.

    • Created a number of new templates.

  • Settings → Detection settings:

    • new anti-virus support: FortiClient (installation and license handled separately from the SOFiE application)

Versions 1.6 and older

These older versions do not have public upgrade notes. All upgrades were performed in close cooperation with Sonpo or a partner.