Upgrade

Upgrade and migration

Riversoft® STCP DirectLink components are distributed as RPM packages in the Riversoft repository and are upgraded with the system package manager, dnf or yum:

Component	Package
Riversoft STCP DirectLink	`stcpdirectlink`
Riversoft STCP DirectLink Portal	`stcpdirectlink-portal`
Riversoft STCP Gemini API	`stcpgemini-api`
Riversoft Console Portal	`stcpgemini-portal`

Migration from version 8 to version 9 has its own procedure, described in Migration from version 8 to version 9.

Best practices

Read the release notes of every version between the installed one and the target. They describe behavior changes, new parameters and specific procedures.
Upgrade a staging environment first and repeat the tests of critical flows before upgrading production.
Plan a maintenance window and notify partners when transfers will be unavailable.
Back up the configuration and the databases before each upgrade.
Upgrade to one target version at a time and keep the same version on every server in the environment.
Record the previous version of each package so you can roll back.

Before upgrading

Survey

Record the installed versions:

rpm -q stcpgemini-api stcpgemini-portal stcpdirectlink stcpdirectlink-portal

Check the versions available in the repository:

dnf makecache
dnf list --showduplicates stcpgemini-api stcpgemini-portal stcpdirectlink stcpdirectlink-portal

Identify transfers in progress and download links that are still valid.
Define who is responsible for the change and the rollback plan.

Backup

Configuration files:

Item	File
Riversoft STCP DirectLink	`/usr/local/stcpdirectlink/configs/config.json`
Riversoft STCP DirectLink Portal	`/usr/local/stcpdirectlink/static/portal/assets/configs/config.json`
Riversoft STCP Gemini API	`/usr/local/stcpgemini-api/configs/config.json`
Riversoft Console Portal	`/usr/local/stcpgemini-api/portal/app/configs/config.json`

License file (applLicense) and secret files referenced in the configuration.
Configuration database and log database, according to the organization’s backup policies.
Certificates and keys used by the services.

Upgrade procedure

Stop the services

Stop Riversoft STCP DirectLink before the API:

systemctl stop stcpdirectlink
systemctl stop stcpgemini-api

Upgrade the packages

Refresh the repository metadata and upgrade the packages:

dnf clean all
dnf makecache
dnf upgrade stcpgemini-api stcpgemini-portal stcpdirectlink stcpdirectlink-portal

To upgrade to a specific version, add the version to the package name, for example dnf upgrade stcpdirectlink-9.0.1.

Review the configuration

The configuration files in use, including the Riversoft STCP DirectLink Portal one, are not replaced by the upgrade. Compare each config.json with the template (example-config.json) of the new version to identify new or changed parameters, as described in the release notes. If the package manager creates files with the .rpmnew extension, compare them with the files in use:

find /usr/local/stcpgemini-api /usr/local/stcpdirectlink -name "*.rpmnew"

Update the database, when required

When the new version requires database changes, the release notes list the scripts and the order in which to run them. Run them with the DBA team.

Start the services

Start the API before Riversoft STCP DirectLink and confirm both are running:

systemctl start stcpgemini-api
systemctl start stcpdirectlink
systemctl status stcpgemini-api stcpdirectlink

Note

When Riversoft STCP Gemini is also installed, the Riversoft STCP Gemini API and the Riversoft Console Portal are shared by both products: upgrade them only once, before the products, checking version compatibility in the release notes.

Post-upgrade validation

rpm -q shows the target version of each package.
systemctl status shows running for the API and for Riversoft STCP DirectLink, with no errors in the log.
The Riversoft Console Portal opens and accepts sign-in.
Riversoft STCP DirectLink Portal opens at /portal and accepts sign-in by a test user.
A test upload and download complete through the portal and the API.
Secure links, notifications and the connectors used in the environment work.

Rollback

If validation fails and the cause cannot be fixed within the maintenance window:

Stop the services.
Return the packages to the previous version recorded before the upgrade:
```
dnf downgrade stcpgemini-api-<previous-version> stcpgemini-portal-<previous-version> stcpdirectlink-<previous-version> stcpdirectlink-portal-<previous-version>
```
You can also undo the whole transaction with dnf history undo <id>, where <id> is the transaction identifier shown by dnf history. With yum, use yum downgrade and yum history undo.
Restore the configuration files from the backup.
If database scripts were run, restore the database backup.
Start the services and repeat the validation.

Important

Rollback depends on the previous version still being available in the repository and on backups of the files and databases taken before the upgrade.

Migration from version 8 to version 9

Migration from version 8 to version 9 changes how configuration and authentication work and has its own procedure, described in the following sections. It is intended for environment administrators and the teams responsible for API integrations. For other versions, follow the upgrade described above and the release notes.

What changes in version 9

In version 8, part of the operational configuration was in the config.json file. In version 9, the configuration is split between the local file and the instance configuration database:

Source in version 9	Contents	Where it is managed
`config.json`	Local startup, database connections, notifications, routing, KMS, telemetry and service.	On the application server. See Configuration.
Configuration database	Instance operational configuration, JWT, SSO and external lock.	Riversoft Console Portal.

Version 9 also consolidates API authentication:

Change	Effect
Protected routes require a Bearer token	Upload, listings, report and sign-out no longer accept Basic. Basic is still accepted only at sign-in (`/auth/login`).
API in version `v2`	The prefix changes from `/directlink/v1` to `/directlink/v2`, and `v1` is no longer served. See Migration from v1 to v2.
Listed-file download with token	`/download/file` and `/download/file/backup` require the Bearer token or the session cookie of the same user who made the listing.
`time` field in ISO 8601	API responses give the date and time in RFC 3339 format, for example `2026-11-07T14:03:21-03:00`.
Token accepted in the header or in the cookie	Integrations use `Authorization: Bearer`; the portal keeps the session in the `__Host-dirl_session` cookie (`HttpOnly`, `Secure`, `SameSite=Strict`). The header takes precedence.
`/auth/token` and `/oauth2/token` are equivalent	Both endpoints issue tokens through the password grant or token exchange, according to the enabled modes.
Token exchange with a provider	The source JWT is validated by the provider given in the `provider` field or, alternatively, in the `X-STCPDIRECTLINK-JWT-ISSUER` header.
Validated identity	The user identified by the credentials or claims must exist and match the profile loaded from the configuration.
Impersonation token	Technical integrations can use a long-lived token, generated in the supervision interface, with a registered session identifier.
Validated host	The API rejects with `403` calls made through a host other than the one configured for the service.
Cloudflare Turnstile (optional)	Sign-in, first access and password recovery can require the Cloudflare challenge.

Parameters moved out of `config.json`

The fields below must not be copied from the version 8 config.json. In version 9, they are loaded from the instance configuration in the database:

Field in version 8	Destination in version 9
`General.oauthTokenMethodJWT`	`CfgInstance.Startup.JwtConfig.MethodName`
`General.oauthTokenExpireSeconds`	`CfgInstance.Startup.JwtConfig.ExpirationTime`
`General.lockProvider.lockType`	`CfgInstance.Startup.ExternalLock*`
`General.ssoProviders[]`	`CfgInstance.Startup.SSOConfigs[]`

When not set, the token signing method is HS256 and the expiration is 3600 seconds. Without an external lock, the application uses a file system lock in the local directory. The configuration database connection fields (cfgProvider, cfgDbHost, cfgDbPort, cfgDbName, cfgDbUser and cfgDbPswd) do not change.

Impact on integrations

Adapt the API consumers before releasing version 9:

Situation in version 8	Adaptation for version 9
Client using `/directlink/v1`	Change the prefix to `/directlink/v2`.
Download through `linkURL` without a token	Send the Bearer token of the same user who made the listing.
Reading the `time` field in the previous format	Read the field in ISO 8601 (RFC 3339) format.
Basic sent directly to `/upload`, `/download/list` or `/report`	Obtain a Bearer token (sign-in or password grant) and send `Authorization: Bearer <token>`.
Token obtained through the password grant	Check the enabled mode, route, form and validity of the new token.
Token exchange without `provider`	Provide the JWT provider in the `provider` field or in the `X-STCPDIRECTLINK-JWT-ISSUER` header.
Automation with a long-lived token	Generate and register an impersonation token, protect the secret and test its rotation.
Portal or SPA receiving the token in the URL	Use the secure cookie session issued at sign-in or by SSO.
Client calling an unregistered route or method	Use the `/directlink/v2` prefix and the method given in the API reference.
Client accessing the API through another host name	Fix the URL, DNS, proxy or `Host` header to the configured address.

Before migrating

Version 8 survey

Identify the instance, the environment and the person responsible for the change.
Make a controlled copy of the version 8 config.json.
Record the provider and connection details of the configuration database.
Record the enabled services and the critical upload, download, authentication and SSO flows.
Identify integrations that send Basic directly to the transfer routes.
Identify integrations that use the password grant, token exchange or long-lived tokens, and the providers and issuers of the tokens.
List the enabled SSO providers and the lock type in use.
Record the effective JWT signing method and expiration.
Define a downtime window and the fallback plan.

Access and prerequisites

Access to the application server, the configuration database and the Riversoft Console Portal.
Backup of the configuration database, the configuration directory and the control files.
Certificates, keys and secrets available in the environment’s secure mechanism.
Disk space and permissions of the version 9 directory checked.

Migration procedure

Prepare version 9

Install version 9 in the directory defined for the instance.
Prepare the version 9 config.json, adjusting only the local parameters: directories, license, database connections, KMS, telemetry, notifications and service.
Remove from the file the parameters moved to the database.
Check file owner, group and permissions and validate the JSON (for example, with jq empty).

Prepare the configuration in the database

Open the instance in the Riversoft Console Portal.
Check the JWT configuration (signing method, expiration and signing material).
Check the authentication modes enabled for the API.
Check the providers used for token exchange and impersonation, the lock provider and the SSO providers. Enable only the providers actually in use.
Save and record the date, the person responsible and the environment of the change.

Adapt and test the integrations

Change consumers that use Basic on protected routes to Authorization: Bearer.
Provide the token exchange provider.
Confirm the /directlink/v2 prefix and the host configured for the API.
Update the secure storage of technical tokens.
Run the authentication tests before the transfer tests.

Start and monitor

Stop version 8 according to the operating procedure.
Start version 9 and follow the startup log.
Confirm that the instance loaded the configuration database without JWT, lock or SSO errors.
Confirm that the service is available before releasing it to users.

Post-migration validation

The service starts without configuration database connection errors.
The host used by clients matches the one configured for the API.
Local sign-in with Basic on /auth/login works, including MFA where applicable.
A token is issued with the expected method and expiration; the password grant and token exchange work in the enabled modes.
The token is accepted in the Authorization header and the portal session works through the cookie.
Sign-out removes the cookie and ends access to protected resources.
A valid impersonation token works and an unregistered identifier is rejected.
Sign-in through each enabled SSO provider works, and the OAuth 2.0 and SAML 2.0 callbacks reach version 9.
Upload, listings, authenticated download, secure link download and report work.
A missing or invalid credential is rejected, and a valid token with a blocked connection receives 403.
The enabled notifications work and the logs show no configuration, authentication or permission errors.

Record the evidence (time, instance, version, route, HTTP status and result). Never record tokens, cookies, passwords, PINs or secrets in the evidence.

Common migration problems

Symptom	Checks
Version 9 does not start	JSON path and validity, license, permissions and startup log.
Database connection error	Host, port, user, password, `cfgDbName`, TLS options and firewall.
Tokens with an unexpected method or expiration	Instance JWT configuration in the Riversoft Console Portal.
`/auth/token` rejects the password grant	Enabled mode, `POST` method, `Content-Type`, `grant_type`, user and password.
Token exchange rejected	`grant_type`, `subject_token_type`, `subject_token`, `provider`, JWT provider registration, issuer and audience.
Valid token receives `401`	Signature, issuer, audience, expiration, provider and match between user and profile.
Valid token receives `403`	Configured host, blocked connection, time window, pre-connection command, service, filters and locks.
Basic stopped working on upload, listing or report	The client still uses the version 8 contract. Obtain a token and use `Authorization: Bearer`.
The cookie does not keep the portal session	HTTPS publishing, domain, `Secure` and `SameSite` attributes, proxy and clock.
SSO sign-in does not appear or the callback fails	Enabled provider, name used in the route, URLs registered with the provider, certificates and clock.
A Portal change does not show up in the application	Correct instance, saved change and service restart or reload.

Migration rollback

Roll back when version 9 cannot be stabilized within the change window:

Stop version 9 and keep the logs of the attempt.
Restore the version 8 configuration file and binary.
Confirm that version 8 points to the expected configuration and services and start it.
Restore the version 8 authentication contract on the clients, if it was changed.
Validate authentication, token issuance, upload, download and the critical flows.
Record the configurations changed in the Portal. Keep those records until the failure is analyzed.

Security during migration

Do not share the full config.json outside the authorized group or record secrets in tickets, emails or evidence.
Keep technical tokens in a secrets vault and define their rotation.
Enable only the authentication modes the environment needs.
Publish the portal and the API over HTTPS to keep the Secure cookie.
Use tls=skip-verify on the database connection only in controlled test environments. See Requirements › TLS connection.
Rotate any credentials that have been exposed.

Installation Security