BeeGFS v8.1.0 Upgrade Guide

Please read and understand the information below completely before attempting the upgrade.

Possible upgrade paths

The following upgrade paths from older versions are supported:

  • v6.x ⟶ v7.4.6 ⟶ v8.0.1 ⟶ v8.1.0

  • v7.x ⟶ v7.4.6 ⟶ v8.0.1 ⟶ v8.1.0

  • v8.0.x ⟶ v8.1.0

When upgrading from BeeGFS 7 or earlier refer to the BeeGFS 8 upgrade guide.

Before Upgrading

  1. Check all servers and clients are on supported Linux distributions and kernel versions.

Upgrade to v8.1.0

  1. If you use buddy mirroring, make sure that all buddies are in GOOD state in the previous output before proceeding.

  2. Stop the BeeGFS system:

    • stop/unmount all clients

    • stop all storage services

    • stop all meta services including any event listeners (if in use)

    • stop the management service

  3. Refer to the backup guide and take a full system backup if possible. If a full backup is not possible ensure you at least take a minimal backup of important system configuration.

    Note

    A minimal backup of important system configuration after stopping all services and before upgrading packages is strongly recommended. Proceed without any backups at your own risk!

  4. Download the BeeGFS package repository file for your distribution to all nodes. Visit the BeeGFS download page and follow the step-by-step directions to add the BeeGFS package repositories to your Linux distribution’s package manager.

  5. Upgrade all BeeGFS packages.

  6. Update required configuration:

    1. If you are using Remote Storage Targets you will need to set a new client parameter sysBypassFileAccessCheckOnMeta=true in the beegfs-client.conf file of the client mount points used by Remote and Sync nodes. You must also ensure these mount points are not used by any other applications/users besides Remote and Sync. For more details see the Prerequisites section of the remote targets documentation.

  7. Start all services and clients and verify that the system works as expected.

  8. After finishing the upgrade run the following commands to verify the upgrade:

    1. Verify all nodes and targets are online and in a good state: beegfs health check

      beegfs health check

      Tip

      If the “Available Capacity” check warns that targets are low on free space, you can adjust the “capacity pool” thresholds defined in the beegfs-mgmtd.toml so they are better suited to your environment.

FAQs

The following section addresses common questions when upgrading BeeGFS.

Why does the management log the database schema is outdated?

After upgrading a system already running BeeGFS 8 to a newer version, the management service refuses to start and logs an error like:

Database schema version 1 is outdated. Please upgrade to latest version 2

Starting in BeeGFS 8, management data is stored in a SQL database. New BeeGFS versions may introduce changes to the database schema, for example to add new fields. The management includes a mechanism for upgrading (i.e., “migrating”) the database schema after an upgrade by manually running:

/opt/beegfs/sbin/beegfs-mgmtd --upgrade

Note

If your database is located at a non-standard path, ensure to also specify --db-file.

The upgrade process will first backup the current database in the same directory as the existing one, with the old version as the suffix. For example by default backups will exist at a path like:

/var/lib/beegfs/mgmtd.sqlite.v1

The backup is mainly needed if you need to downgrade BeeGFS. Because the database size is typically small, it is recommended to keep around at least one previous version indefinitely.

Provided the backup succeeds the database upgrade will be attempted. If for some reason the upgrade fails an error will be logged, for example if you tried to upgrade between unsupported versions. If the resolution is not clear please open a support ticket. If you choose to downgrade in the meantime, please perform the following steps:

  • Record the error(s) logged from the --upgrade.

  • Downgrade all BeeGFS packages.

Note if the upgrade fails the original database file will be left untouched, so there should be no reason to overwrite the current database file with the backup after a failed database upgrade. The backup is intended if you need to downgrade BeeGFS for some other reason.