Upgrade and migration

Riversoft® STCP Gemini Rename is distributed as an RPM package (stcpren), in the Riversoft repository, and as a DEB package. It is upgraded with the system package manager.

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 version:

  stcpren -v

• On Enterprise Linux, check the versions available in the repository:

  dnf makecache
  dnf list --showduplicates stcpren

• Identify the events, external commands and schedules that trigger Riversoft STCP Gemini Rename during the maintenance window.

• Define who is responsible for the change and the rollback plan.

Backup

• Configuration file /usr/local/stcpren/configs/config.json.
• Configuration database, where the routings are stored, according to the organization’s backup policies. For a quick copy of a routing, use -export.
• In the local file mode, the routing JSON files.
• The sequence number files (.seq) in the applLockDir directory.

Upgrade procedure

dnf clean all
dnf makecache
dnf upgrade stcpren

yum clean all
yum makecache
yum update stcpren

apt install ./stcpren-<version>_amd64.deb

find /usr/local/stcpren -name "*.rpmnew"

stcpren -v
stcpren -db -rules <ROUTING> -scan <source-directory> -test

Post-upgrade validation

• stcpren -v shows the target version.
• The routing test (-test) shows the expected rules, with no MSG7003.
• A routing triggered by an event or a schedule processes files as expected.
• The suspended schedules were re-enabled.

Rollback

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

1. Suspend executions again.

2. Return the package to the previous version recorded before the upgrade:

   dnf downgrade stcpren-<previous-version>

   You can also undo the transaction with dnf history undo <id>. With yum, use yum downgrade and yum history undo. On Ubuntu, install the DEB package of the previous version.

3. Restore the configuration file from the backup.

4. Repeat the validation and re-enable the schedules.

Migration between major versions

When a version requires migration, with changes to parameters, rules or behavior, the specific procedure is published in the release notes. Follow that procedure instead of the simple upgrade described on this page.

INI rule conversion

Rules from earlier versions in INI format can be converted to the JSON format used in this version:

stcpren -ini /path/rules.ini -rules /usr/local/stcpren/configs/rules.json

The conversion reads the General section and the FileMatching section, in which the Rule0, Rule1 and following keys point to the sections that define each rule. The result is recorded in messages MSG7039 (success) or MSG7038 (failure).

After the conversion:

1. Review the generated file. See Rule reference.

2. Test with -test on sample files:

   stcpren -rules /usr/local/stcpren/configs/rules.json -scan <test-directory> -test

3. Use the file in the local file mode, or register the routing in the Riversoft Console Portal for the database mode.