Workbench Server Update Instructions

Assumptions

• This is an update from version 22.2.x or above. To update from an earlier version, please update to 22.2.x first.

• Target version is 2026.1.0

• Existing Workbench is installed at /fossid
• Database tables permissions and role_permission have not been modified.

Package changes

As of version 23.3 we have added the ability to rotate the FossID Workbench logs

OS requirements

FossID Workbench is supported on:

• Debian 11, 12, 13
• Ubuntu 22.04, 24.04, 26.04
• RedHat Enterprise Linux 8, 9, 10
• RedHat Enterprise Linux Server 8, 9, 10
• AlmaLinux 8, 9, 10
• RockyLinux 8, 9, 10

The minimum PHP required version is 8.3.

The minimum required version of the database server is MySQL Server 8.0 or MariaDB 10.6. However, we recommend that all sub-systems are at least in their oldest still maintained version.

Optional preparation for updating to 22.2

Updating a Workbench installation with a large database to 22.2 or to current version coming from version older than 23.1 might take a very long time due to a specific database change. During the update it is not possible to use the webapp.

It is possible to prepare for the update by connecting to the database and executing the following statement:

ALTER TABLE "file_client_results" MODIFY "file_license" mediumtext NULL;

Once this is completed, which is the part that will take a long time, the actual update will not take longer than usual.

PHP prerequisites

If your FossID server is running on Debian 11, Debian 12 or Ubuntu 22.04, Redhat 8 or RHEL Server 8 you need to add a repository with a php version equal or greater than 8.3 first:

Debian 11, Debian 12

sudo apt-get update
sudo apt-get -y install lsb-release ca-certificates curl
sudo curl -sSLo /tmp/debsuryorg-archive-keyring.deb https://packages.sury.org/debsuryorg-archive-keyring.deb
sudo dpkg -i /tmp/debsuryorg-archive-keyring.deb
sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/debsuryorg-archive-keyring.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list'
sudo apt-get update

Ubuntu 22.04

sudo add-apt-repository ppa:ondrej/php -y
sudo apt update

RedHat

EPEL repository on RedHat

For RHEL-based OSes 8

sudo yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm -y

For RHEL-based OSes 9

sudo yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm -y

For RHEL-based OSes 10

sudo yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-10.noarch.rpm -y

Remi’s RPM Repository

For RHEL-based OSes 8

sudo yum install -y https://rpms.remirepo.net/enterprise/remi-release-8.rpm

For RHEL-based OSes 9

sudo yum install -y https://rpms.remirepo.net/enterprise/remi-release-9.rpm

For RHEL-based OSes 10

sudo yum install -y https://rpms.remirepo.net/enterprise/remi-release-10.rpm

Install packages

Set the desired version of PHP (minimum required version is 8.3):

sudo yum module reset php
sudo yum module enable php:remi-8.3 -y

sudo yum install bash bzip2 coreutils curl findutils git glibc grep gzip java-21-openjdk-headless \
            lbzip2 libxslt p7zip p7zip-plugins perl \
            php-cli php-curl php-fpm php-json php-ldap php-mbstring php-mysqlnd php-process php-xml php-zip php-intl \
            sudo tar unzip vim wget xz zip -y

MySQL/MariaDB upgrade

Due to the older version in different distributions of MySQL or MariaDB, we recommend upgrading to at least MySQL 8.0 using the official guides at https://dev.mysql.com/doc/refman/8.0/en/installing.html or, for MariaDB 10.6 from https://mariadb.com/kb/en/binary-packages/.

NOTE: It is recommended to explicitly set these values for character set and collation in your MySQL/MariaDB config file:

character-set-server     = utf8mb4
collation-server         = utf8mb4_general_ci

For MySQL Replication, particularly when replicating from MySQL 5.7 (or earlier) to MySQL 8.x, the parameter default_collation_for_utf8mb4 should be set to utf8mb4_general_ci on both the source and replica servers to ensure compatibility. Note: This parameter cannot be set in my.cnf or as a command-line startup option. It must be set at runtime using SET PERSIST default_collation_for_utf8mb4='utf8mb4_general_ci'; or SET GLOBAL default_collation_for_utf8mb4='utf8mb4_general_ci'; after the MySQL server has started. This parameter is only necessary when replicating from older MySQL versions (5.7 or earlier) that used utf8mb4_general_ci as the default to MySQL 8.x (which uses utf8mb4_0900_ai_ci as the default). For new MySQL 8.x deployments without replication from older versions, this parameter is not required. More details here: https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_default_collation_for_utf8mb4

A value of at least 64M needs to be set for max_allowed_packet under [mysqld] tag in the corresponding file for your mysql server distribution (e.g. /etc/mysql/my.cnf or /etc/my.cnf). See below reference:

[mysqld]
max_allowed_packet = 64M

This may vary for each Linux distribution and mysql server distribution. Please review the documentation for your corresponding Linux and mysql version distribution.

Restart mysql:

sudo service mysql restart

Access Deliverables

Access info to the FossID deliverables is provided in the delivery mail.

Install the package

DEB installer

sudo apt install ./fossid-release_regular_amd64-<version>.deb -y

RPM installer

sudo yum localinstall ./fossid-release_regular.x86_64-<version>.rpm -y

Remove old PHP versions (Debian/Ubuntu)

After the package has been installed, remove any unsupported PHP versions. This must be done after the package install so that the package manager resolves all PHP dependencies consistently for the new version.

IMPORTANT: On Debian and Ubuntu, PHP configuration files are stored per version under /etc/php/<VERSION>/. Before removing old PHP versions, migrate any customizations you have made to the newly installed PHP version. Common files to check:

• PHP-FPM pool config: /etc/php/<OLD_VERSION>/fpm/pool.d/www.conf → /etc/php/<NEW_VERSION>/fpm/pool.d/www.conf
• PHP CLI config: /etc/php/<OLD_VERSION>/cli/php.ini → /etc/php/<NEW_VERSION>/cli/php.ini
• PHP-FPM config: /etc/php/<OLD_VERSION>/fpm/php.ini → /etc/php/<NEW_VERSION>/fpm/php.ini

If you copy www.conf from the old version, update the listen directive so that the socket path references the new PHP version. For example, when upgrading from PHP 8.2 to PHP 8.3, change:

listen = /run/php/php8.2-fpm.sock

to:

listen = /run/php/php8.3-fpm.sock

Alternatively, instead of copying the file, manually re-apply your changes to the new version’s default configuration files, which already contain the correct socket path.

NOTE: FossID Workbench expects a single supported PHP version on the host so the runtime, php-fpm, and PHP extensions stay aligned. Removing old PHP versions before installing the updated FossID Workbench package can leave a mismatch between the PHP runtime and modules; always install the package first, then remove unsupported PHP versions. If you must keep another PHP version on the same machine for other applications, confirm that the FossID PHP version still has every package and extension required by this release (compare with the installation guide and your package manager); missing modules for the version FossID uses are a common cause of upgrade or runtime failures.

Update nginx.conf

Please update the nginx.conf configuration, either update the existing file or copy and overwrite the new file:

sudo cp /fossid/setup/templates/nginx.conf.dist /etc/nginx/nginx.conf

Edit the file and uncomment the line for the your system.

# Hide the Server header
# load_module modules/ngx_http_headers_more_filter_module.so; # for debian based systems
# include /usr/share/nginx/modules/*.conf; # for rhel based systems

Example for RHEL systems:

# Hide the Server header
# load_module modules/ngx_http_headers_more_filter_module.so; # for debian based systems
include /usr/share/nginx/modules/*.conf; # for rhel based systems

Update fossid.conf

As of FossID Workbench 23.3, changes need to be done in fossid.conf if you were previously using Microsoft OAuth2 login as some parameters were renamed/added to support multiple identity providers:

1. “webapp_microsoft_oauth2_login” has been renamed to “webapp_oauth2_login”
2. “webapp_microsoft_oauth2_fallback_local_login” has been renamed to “webapp_oauth2_fallback_local_login”.
3. parameter webapp_oauth2_provider=”Microsoft” needs to be added to fossid.conf.

As of FossID Workbench 21.2 it is no longer necessary or recommended to migrate your fossid.conf settings. The Workbench will work with your existing pre-21.2 configuration.

If you still want to migrate your old settings to the new template for any reason this is how:

1. Backup the existing /fossid/etc/fossid.conf file to e.g. fossid.conf_bak
2. Rename /fossid/etc/fossid.conf.dist to /fossid/etc/fossid.conf
3. Modify the new /fossid/etc/fossid.conf file to match your configuration in the fossid.conf_bak

Configure Workbench URL

This setting is required for the application to function properly. It is also used to generate correct absolute URLs in emails:

webapp_base_url = https://mycompany.com/index.php

Save your fossid.conf file.

NOTE: The changes to configuration is immediate, no restart is required.

Post install actions

Update database

Review this section if you used the Workbench Manage Backups utility to restore a database as further steps may be required. Make sure you import the same version of the database the backup was created from as you may not be able to import, for example, a database from MariaDB 10.6 and trying to restore it in a server with MySQL 8.0.

Starting from 22.2 version new unique constraints are added at database level to avoid duplicate data.

In order to help identifying and fixing eventual existing duplicates the following command needs to be executed from /fossid/webapp directory:

cd /fossid/webapp
sudo -u www-data php bin/console.php enforce_data_integrity

An interactive command-line interface will guide you trough the process. For duplicated licenses or components the script will help you fix the duplicates by reassigning the identifications to one record and removing the duplicated one (so no identification is lost). For projects/scans/users duplicated will be fixed by adding some suffix.

The system checks if there is a duplicates in DataBase tables: 
'licenses'; 
'projects'; 
'components'; 
'scans'; 
'users'; 
----------------------- 
The system didn't find duplicates. Do you want to add UNIQUE CONSTRAINTS to the tables? (defaults to yes)
  [0] yes
  [1] no
  > 0

In the best scenario there are no duplicates found and unique constraints can be directly added. If indeed duplicates are found the following message is displayed:

"The system found duplicates in the next tables:"
'projects'
'licenses'
----------------------- 
Do you want to clean duplicates? (defaults to yes)
  [0] yes
  [1] no
 > 0

The following tables and columns are used for checking uniqueness of the data:

  Table       unique by    Column(s)
 'projects'                'project_code' 
 'licenses'                'identifier' 
 'components'              'name' and  'version' 
 'scans'                   'code', 
 'users'                   'username'  

Please follow instructions displayed by interactive CLI to fix any duplicates found. Last step is adding unique constraints to the those tables. If the unique keys already exists an error message is displayed:

The system didn't find duplicates. Do you want to add UNIQUE CONSTRAINTS to the tables? (defaults to yes)
  [0] yes
  [1] no
 > 0
The system tries to add UNIQUE CONSTRAINT 'uc_identifier' to table: 'licenses' on column: `identifier`.
SQLSTATE[42000]: Syntax error or access violation: 1061 Duplicate key name 'uc_identifier'

No other action needs to be taken as the unique key is already in place.

A one time action is required for migrating component identifications made before release 20.1:

Before release 20.1 it was possible to assign as identification just one component per file identified. Run one time the below command to migrate any old component identification from column “component_id” in table “identifications” to table “identification_component”. The column “identifications.component_id” is removed in 24.3 release by dbupdate.php script.

sudo -u www-data php bin/console.php migrate_legacy_identifications --auto_migrate

A one time action is required when updating from a version before 23.1.x:

sudo -u www-data php bin/console.php split_file_client_results

The table file_client_results will be split in one table per scan. This will alleviate database maintenance by immediately regaining disk space from MySQL when a scan is deleted by dropping the file_client_results_x table associated with deleted scan. Please inspect if tables with name like file_client_results_SCAN_ID were created.

The initial table file_client_results still exists with name old_file_client_results and can be dropped manually after checking if new tables were created and data migrated.

After fixing duplicates and running split_file_client_results command continue the regular upgrade process.

Navigate to the setup folder:

cd /fossid/setup/database

Verify with the below query if row_format is set as DYNAMIC or COMPRESSED in all tables, otherwise you will need to manually change them with the ALTER TABLE statement more below.

To verify if row_format is set to DYNAMIC or COMPRESSED on each table:

SELECT table_name, row_format FROM information_schema.tables WHERE table_schema=DATABASE();

To manually modify the table if needed (in the example below is set to DYNAMIC):

ALTER TABLE [table_name] ROW_FORMAT=DYNAMIC;

sudo -u www-data php dbupdate.php /fossid/etc/fossid.conf

sudo -u www-data php db_info_update.php /fossid/etc/fossid.conf

sudo -u www-data php licenseupdate.php --no-update --no-disable /fossid/etc/fossid.conf

For complete licenseupdate.php manual please run:

php licenseupdate.php --help

Optional PURL and CPE update from KB

PURL field was added in Workbench 23.1. In order to try filling this field from KB for already existing components in Workbench database run this command. Also this command will fill CPE info from KB if local Component has this field empty:

cd /fossid/webapp
sudo -u www-data php bin/console.php add_purl_and_cpe

Update OSS Review Toolkit for Dependency Analysis

There are two tools: FossID-DA or OSS Review Toolkit that can be used to provide information on package dependencies and their license information right in the FossID Workbench user interface. Using the Dependency Analysis feature, you can get a better insight into the licenses your software needs to be compliant with. FossID also provides API for the Dependency Analysis so it can be included in your Continuous Integration pipeline.

Since Workbench 24.3 release the FossID-DA tool is the default dependency analysis tool. For more details about FossID-DA please see the dedicated documentation section here

See the Installation - Dependency Analysis for additional details on installing OSS Review Toolkit.

Changes to the nginx configuration

New locations, URL rewrites, security headers, and error handling have been added to the nginx configuration over successive releases. If you have a hand-modified nginx.conf, you must merge these changes in. Two approaches are described below.

Option A — Replace with the dist template (recommended)

Copy the template and re-apply your site-specific settings:

sudo cp /fossid/setup/templates/nginx.conf.dist /etc/nginx/nginx.conf

After copying, edit the file and restore any values from your previous configuration:

• listen — port (80) or SSL block (443)
• ssl_certificate / ssl_certificate_key — paths to your certificate and key (if using HTTPS)
• server_name — your server’s domain name
• fastcgi_pass — PHP-FPM socket path; must match your installed PHP version (e.g. php8.3-fpm.sock)
• Subdirectory rewrite block — if the FossID Workbench is deployed at a non-root path

Validate and restart nginx:

sudo nginx -t && sudo systemctl restart nginx.service

Option B — Manual merge

If you cannot replace the file wholesale, verify that each of the following blocks is present in your configuration.

React application routing (/nui)

Required for the React-based UI. Without this block, all /nui URLs return 404.

location ~ /nui {
    add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self' data:; connect-src 'self'; worker-src 'self' blob:; frame-ancestors 'none';" always;

    rewrite ^(.*)/nui$ $1/react/index.html last;
    rewrite ^(.*)/nui/assets/(.*)$ $1/react/assets/$2;
    rewrite ^(.*)/nui(/.*nui)(/.*)\.(js|svg|gif|ttf|png)$ $1/react$3.$4 last;
    rewrite ^(.*)/nui(/.*)\.(js|svg|gif|ttf|png)$ $1/react$2.$3 last;
    rewrite ^(.*)/nui(/.*)$ $1/react/index.html last;
}

Health check endpoint

location = /health-check {
    rewrite ^/health-check$ /index.php?check_health last;
}

Block direct access to check_health.php

location ~ check_health\.php$ {
    return 404;
}

Block direct access to all PHP files except index.php (security)

This must come after the location = /index.php exact-match block.

location ~ \.php$ {
    return 404;
}

Dynamic error page (/error.html)

location = /error.html {
    set $error_code $status;
    if ($error_code = '') {
        set $error_code $arg_status;
    }
    if ($error_code = '') {
        set $error_code 500;
    }

    sub_filter 'STATUS_CODE_PLACEHOLDER' '$error_code';
    sub_filter_once on;
    sub_filter_types text/html;

    default_type text/html;
    try_files $uri =404;
}

Error page directives

Custom error pages require error_page directives for all relevant HTTP status codes. Copy the full list from /fossid/setup/templates/nginx.conf.dist into the server {} block. Example entries:

error_page 400 =400 /error.html?status=400;
error_page 403 =403 /error.html?status=403;
error_page 404 =404 /error.html?status=404;
error_page 500 =500 /error.html?status=500;
error_page 502 =502 /error.html?status=502;
error_page 503 =503 /error.html?status=503;

Content Security Policy in the root location

location / {
    add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self' data:; connect-src 'self'; worker-src 'self' blob:; frame-ancestors 'none';" always;
    try_files $uri $uri/ =404;
}

Timeout settings

Required for long-running scan requests. These must be inside the server {} block.

send_timeout 1200;
fastcgi_read_timeout 1200;
fastcgi_send_timeout 1200;
fastcgi_connect_timeout 1200;

Legacy URL rewrites

Verify the following rewrite blocks are present to support API and legacy /webapp/ URLs:

location ~ /api/[a-zA-Z0-9_]+/[a-zA-Z0-9_] {
    rewrite (.*)/api/[a-zA-Z0-9_]+/[a-zA-Z0-9_] $1/index.php last;
}

location ~ /scim/[a-zA-Z0-9_] {
    rewrite (.*)/scim/[a-zA-Z0-9_] $1/index.php last;
}

location ~ /webapp/(index|api|api_upload_endpoint)\.php$ {
    rewrite (.*)/webapp/(.*) $1/$2 last;
}

location ~ /(api|api_upload_endpoint)\.php$ {
    if ($request_method = POST) {
        rewrite (.*)/(api|api_upload_endpoint)\.php $1/index.php last;
    }
    rewrite (.*)/(api|api_upload_endpoint)\.php $1/index.php redirect;
}

location ~ /webapp/ {
    rewrite (.*)/webapp/(.*) $1/$2 redirect;
}

location ~ /webapp$ {
    rewrite (.*)/webapp $1/ redirect;
}

After making changes, validate and restart nginx:

sudo nginx -t && sudo systemctl restart nginx

Changes required when upgrading PHP

If you have upgraded PHP, please make the following changes.

Open the /etc/nginx/nginx.conf and look for the following section:

location = /index.php {
    # If any other php version than 8.3 is used, please update this path
    fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param SCRIPT_NAME $fastcgi_script_name;
}

Change the fastcgi_pass unix:/run/php/php8.3-fpm.sock; to point to the right version of php. For example, if php version is 8.4, the line should look like this:

fastcgi_pass unix:/run/php/php8.4-fpm.sock;

Restart nginx service:

sudo systemctl restart nginx

Edit /etc/php-fpm.d/www.conf and make sure the following configuration is set:

user = www-data
group = www-data
listen = /run/php/php8.3-fpm.sock
listen.owner = www-data
listen.group = www-data
listen.mode = 0660
;listen.acl_users = apache,nginx   <-- make sure it's commented out.

Change the listen = /run/php/php8.3-fpm.sock to point to the right version of php. For example, if php version is 8.4, the line should look like this:

listen = /run/php/php8.4-fpm.sock

Change the group ownership of /var/lib/php and then restart the php-fpm:

sudo chgrp www-data /var/lib/php/*
sudo systemctl restart php-fpm

Log rotation

As of Fossid Workbench 23.3 we have added the files needed for rotating the logs in /fossid/logs. The configuration can be tuned to the usage needs by editing the file /etc/logrotate.d/fossid-workbench.

Remove old crontab entries

As of FossID 21.2, crontab is no longer used for background tasks (Vulnerability monitoring and scan queue handling). If you are upgrading an installation that had background tasks configured, run:

sudo crontab -e

and delete any entries similar to:

* * * * *  /fossid/www/webapp/scans_queue_consumer.sh
0 1 * * *  /fossid/www/webapp/cpe_update_check.sh
0 0 * * *  /fossid/www/webapp/monitor.php --check v --n