Upgrading to MooseFS 4: A Comprehensive Guide

January 17th, 2025 | MooseFS Team

Upgrading your MooseFS instance to version 4 ensures better performance, enhanced features, and continued support. This guide will walk you through the process, offering clear instructions for safe and secure upgrades.

---

Package Names

In this guide, we use package names corresponding to the Pro version of MooseFS wherever the instructions for Pro and CE versions are identical. If you’re using MooseFS CE, simply remove the -pro from the package names while following the instructions.

---

Preparation Before Upgrading

To ensure a seamless upgrade process, follow these essential steps:

1. Review the NEWS File

Read the NEWS file included with the MooseFS distribution. It contains details about new features and changes that might require additional actions, such as updating configuration options.

2. Check Your Chunk Matrix

Inspect your chunk matrix via the GUI or CLI to confirm there are no endangered or undergoal chunks. If any exist, wait for the system to replicate them. Address any hardware issues, such as faulty disks, before proceeding.

3. Plan Your Timing

Schedule the upgrade during a low I/O period or disconnect all client processes. While upgrades can be performed during regular operation, module restarts may temporarily delay I/O operations. Ensure external processes have sufficient I/O timeouts to avoid errors.

4. Save Metadata

Before upgrading, use the mfssupervisor tool (if on MooseFS 4) to save the master’s metadata. For Pro users, use the “all servers with CRC check” mode and verify metadata consistency via the GUI or CLI.

Backup Master’s Metadata

Before upgrading the master module, back up your master’s metadata. For Pro users, this backup is necessary only before upgrading the first master follower.

Finding Metadata Files:

1. Check the DATA_PATH variable in the master’s configuration file.
2. Locate metadata.mfs.back and changelog.*.mfs files in this directory. Copy them to a secure location.

Note: If you stop (not restart) the master process during the upgrade, back up the metadata.mfs file instead.

---

Upgrading from Previous Major Versions to MooseFS 4

While MooseFS strives for backward compatibility, we recommend the following steps for a reliable upgrade:

Upgrade CE to CE or Pro to Pro

Upgrade incrementally through major versions. For example, upgrade from 2.1.7 to 2.1.12, then to 3.0.118, and finally to the latest MooseFS 4 version.

Upgrade CE to Pro

1. Upgrade to the Latest CE Version First
   Whenever possible, upgrade your instance to the latest available CE version before switching to Pro. If upgrading to the latest CE version is not feasible, contact MooseFS Pro Support for personalized guidance.
2. Switching and Upgrading Simultaneously
   A version upgrade combined with a switch from CE to Pro is possible but not recommended. This approach introduces additional complexity and risks. If this is your only option, always consult MooseFS Pro Support for tailored guidance and instructions, as the procedure can vary based on your current version and specific setup.
3. Special Upgrade Order for CE to Pro
   Unlike other upgrade scenarios, the package upgrade order for CE to Pro differs:
   • First, upgrade all chunkservers to the Pro version.
   • Next, upgrade the master(s) to the Pro version.
   • Finally, upgrade and remount the client mounts.

Switching from Pro to CE

Switching is only possible between identical versions (e.g., 4.57.1 Pro to 4.57.1 CE). Follow the upgrade order for minor version upgrades and remove any obsolete packages afterward.

---

Upgrading Between Minor Versions of MooseFS 4

MooseFS 4 uses a three-part version numbering system (e.g., 4.55.5):

• Major Version: Indicates the product generation (e.g., 4).
• Minor Version: Significant feature updates or changes.
• Patch Level: Bug fixes and minor adjustments.

Upgrade Rules:

1. Modules with the same minor version but different patch levels are compatible.
2. Modules with different minor versions must follow these compatibility rules:
   • Metalogger ≥ Master
   • Master ≥ Chunkserver
   • Master ≥ Client
   • Chunkserver ≥ Client
   • For Pro, Master Follower ≥ Master Leader
3. GUI Recommendation: The GUI module should match or exceed the master’s version for optimal functionality.

---

Step-by-Step Upgrade Instructions

1. Upgrade GUI, CLI, and Netdump

Upgrade the moosefs-pro-cgi, moosefs-pro-cgiserv, moosefs-pro-cli, and moosefs-pro-netdump packages (if applicable). Restart the required services for changes to take effect.

2. Upgrade Metalogger

Upgrade the moosefs-pro-metalogger package (if applicable) and restart the metalogger process.

3. Upgrade Master(s)

• CE: Upgrade the moosefs-master package and restart the process. Wait for all chunk servers to reconnect and complete chunk registration (visible in the GUI’s INFO tab).
• Pro:
  • Upgrade each master follower module (moosefs-pro-master) one by one. Restart each process and wait for it to reconnect and sync as a functioning follower.
  • Upgrade the master leader last. Restarting the leader will promote a follower to leader. Use mfssupervisor to restore leadership to the original master if needed.

4. Upgrade Chunkservers

Upgrade the moosefs-pro-chunkserver packages one by one, restarting each process. Wait for chunk registration to complete before proceeding to the next chunkserver.

5. Upgrade Clients

Upgrade the moosefs-pro-client package and remount the filesystem. Client upgrades can be performed in parallel.

---

Conclusion

Following these steps will ensure a smooth upgrade to MooseFS 4. If you encounter any issues, consult the official MooseFS documentation or contact support. Stay updated with the latest improvements and maintain optimal performance by upgrading your system today!