Regardless of the application version from and to which the update or upgrade is proceeding, the following rules and recommendations apply.
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.
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.
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.)
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.
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.
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.
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:
# RHEL 7 and similar yum upgrade # RHEL 8 and similar dnf upgrade |
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:
shutdown -r now |
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.
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.
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)
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
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:
/etc/nginx/conf.d/default.conf.18048.2022-09-05@09:16:45~ /etc/nginx/nginx.conf.17998.2022-09-05@09:16:43~ |
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.
Edit the file /etc/nginx/proxy.conf and add the following line to the end:
proxy_buffering off; |
After this change it is necessary to restart or reload nginx:
systemctl restart nginx |
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:
location /api/ {
client_max_body_size 0;
proxy_pass http://127.0.0.1:9090/api/;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_http_version 1.1;
proxy_request_buffering off;
}
location ~/admin/download-file/(.+) {
include download.conf;
auth_request /download-file-auth-admin;
}
location ~/admin/download-archive/(.+) {
include download.conf;
auth_request /download-file-auth-admin;
}
location ~/download-file/(.+) {
include download.conf;
auth_request /download-file-auth-user;
}
location ~/download-archive/(.+) {
include download.conf;
auth_request /download-file-auth-user;
}
location /download-file-auth-user {
include download-auth.conf;
proxy_pass http://127.0.0.1:9090/api/user$request_uri;
}
location /download-file-auth-admin {
include download-auth.conf;
proxy_pass http://127.0.0.1:9090/api$request_uri;
} |
In their place add the following new sections:
add_header X-Content-Type-Options "nosniff";
add_header Referrer-Policy "same-origin";
location /api/ {
set $x_uri_suffix "";
include proxy.conf;
}
location /admin/download-file/ {
set $x_uri_suffix "/api";
include proxy.conf;
}
location /admin/download-archive/ {
set $x_uri_suffix "/api";
include proxy.conf;
}
location /download-file/ {
set $x_uri_suffix "/api/user";
include proxy.conf;
}
location /download-archive/ {
set $x_uri_suffix "/api/user";
include proxy.conf;
} |
Create a new file: /etc/nginx/proxy.conf with the following contents:
client_max_body_size 0; proxy_pass http://127.0.0.1:9090$x_uri_suffix$request_uri; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_http_version 1.1; proxy_request_buffering off; |
After those changes it is necessary to restart or reload nginx:
systemctl restart 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)
These older versions do not have public upgrade notes. All upgrades were performed in close cooperation with Sonpo or a partner.