# Minecraft Server Updater **This mod is experimental!** **Minecraft Server Updater (MSU)** is a server-side Fabric utility for keeping a Minecraft server up to date with Modrinth-backed checks, safe staging, wrapper-based installs, automation, and rollback support. MSU is designed for server owners who want update control without replacing live jars while the server is running. > **Core idea:** > Check what is outdated, stage safe updates into a holding area, then let the wrapper apply them cleanly before the next server boot. --- ## Highlights - **Safe update flow:** check → stage → apply on restart - **Modrinth-backed mod resolution** - **Supports mod lists, reference mod folders, and `.mrpack` files** - **Fabric Loader / server launcher maintenance** - **Optional Minecraft version upgrade checks** - **Self-update support for MSU** - **Automation modes for check, stage, or install workflows** - **Rollback and boot verification** - **Operator-only `/msu` commands** - **Readable status output with clear safe-to-stage reasons** ---

✨ Feature set

### Safe check → stage → apply workflow MSU does **not** replace running mod jars while the Minecraft server is live. Instead, it uses a three-step process: 1. **Check** — query Modrinth and inspect the configured source. 2. **Stage** — download or prepare replacement files into `.minecraft-server-updater/`. 3. **Apply** — on the next wrapper start, staged files are installed before Fabric starts. This keeps update actions predictable and avoids modifying jars that the server is currently using. ### Mod update checks MSU checks whether configured mods have newer compatible builds for the **Minecraft version the server is running right now**. Supported mod sources: | Source type | What it does | | --- | --- | | `mod-list` | Tracks one Modrinth project slug, id, or exact name per line in `.minecraft-server-updater/mod-list`. | | `mods-folder` | Uses jars in a reference folder as the managed mod set. | | `mrpack` | Uses a Modrinth pack file or URL as the managed source. | Mod-list entries resolve only by direct Modrinth project id/slug or an exact search hit — MSU does not guess from ambiguous names. ### Server maintenance MSU can check and stage server-side maintenance for the **current** Minecraft version, including Fabric Loader and launcher sync when enabled. ### Minecraft upgrades When `server-upgrade` is enabled, MSU can check readiness for: - Latest Minecraft release - A specific target Minecraft version **Server upgrades are separate from routine mod checks.** Mod checks always target the version the server is actually running. Server upgrade checks target the configured upgrade version and may include: - Minecraft server jar - Fabric launcher / loader for the target version - **Fabric API for the target version** (shown under server update candidates, not as a normal mod-list update) - Optional **mod preflight** for the upgrade target when enabled ### Self-update MSU can check whether a newer MSU build is available on Modrinth and stage its own replacement for the next restart. Server upgrades to a new Minecraft version may require a target-compatible MSU build to be staged together. ### Combined staging `/msu stage all` can combine safe selected targets into one staged restart plan, allowing server maintenance, mod updates, self updates, and compatible Minecraft upgrades to apply on one restart with one backup. If a server upgrade is configured but **not safe to stage**, combined staging stops there and does not stage other targets until server preflight is resolved.

---

📋 Understanding check output

MSU reports safety on separate lines so you can see **whether staging is allowed** and **why not**. ### Safe-to-stage lines | Line | Meaning | | --- | --- | | `Server safe to stage: true` | Server maintenance or upgrade can be staged. | | `Server safe to stage: false; …` | Server staging is blocked; the reason is on the same line (for example missing MSU or Fabric API on Modrinth for the target version, or mod preflight failure). | | `Safe to stage mods: true/false` | Whether `/msu stage mods` is allowed for the **running** Minecraft version. | | `Mods stage blocked: …` | Shown when mod staging is blocked (for example `no updates available`, unknown jars, policy blocks, or mrpack exact-pack issues). | | `Mods ready for target: true/false` | Whether managed mods look ready for a **configured server upgrade target** (preflight only; not the same as “updates available today”). | ### Two Minecraft versions in one `check all` `/msu check all` can show both: - **`check server`** — uses the **upgrade target** (for example 26.2) when upgrade is enabled - **`check mods`** — uses the **running** version (for example 26.1.2) That is intentional, but easy to misread. Example: - Server section: `Fabric API [missing → 0.152.1+26.2]` means the **server upgrade** will install Fabric API for the target version — not that your mod checker found a routine mod update. - Mod section: `0 updates available` means nothing needs staging **on the version you are running now**, even if an upgrade is planned. ### What blocks `stage all` Combined staging follows safety in order: 1. If a server **upgrade** is available but `Server safe to stage: false`, **`stage all` stops** and does not stage mods or self until server preflight passes. 2. Mods are included when safe for the combined plan — including some upgrade cases where mods have no updates on the running version but are still ready for the target. 3. Self-update is staged only when safe and not already handled as part of a required server-upgrade MSU swap. Use `/msu status` after staging to see the combined plan before restart.

---

🧩 Supported update sources

MSU is built around a configured update source. ### `mod-list` Best for servers where you want to keep a chosen list of Modrinth projects up to date. Default file: `.minecraft-server-updater/mod-list` (one project per line; not a JSON array). Example: ```text fabric-api lithium c2me-fabric ``` MSU resolves those projects through Modrinth and checks for compatible builds for the **running** Minecraft version. ### `mods-folder` Best for servers that keep a reference folder of known-good jars. Default folder: `.minecraft-server-updater/mods-folder`. MSU reads the reference jars, identifies Modrinth projects where possible, and manages updates from that set. ### `mrpack` Best for servers based on a Modrinth modpack. MSU can manage projects from a `.mrpack` file or a Modrinth pack URL. `advanced.mrpackMode` controls behavior: | Mode | Behaviour | | --- | --- | | `exact` (default) | Stage the exact pack files and hashes; strict Minecraft / loader checks. | | `tracking` | Treat pack project ids as a managed list and resolve latest compatible builds. |

---

🛡️ Safety model

MSU is designed to avoid risky live replacement. ### It does not hot-swap running jars The server keeps using the currently loaded files until restart. ### Staged updates are held separately Downloads and replacement files are prepared in the MSU staging area first. ### The wrapper applies updates before boot When the server is started with the wrapper, MSU applies the staged plan before Fabric starts. Without `--wrap`, you can still check and stage, but nothing applies on restart. ### Rollback support When a staged plan is applied, MSU can record backup metadata. If boot verification fails, rollback support helps restore the previous working files. ### Unknown/custom jars are handled carefully Unknown jars can be reported and held by local filename policy, but MSU does not treat them as Modrinth-managed or compatibility-checked unless they can be resolved. ### Server upgrade preflight When enabled, MSU checks that managed mods (and required dependencies) look compatible with the **target** Minecraft version before allowing a server upgrade to stage. Fabric API for the target version is handled as part of the server upgrade path when needed. ### Destructive unmanaged mod removal When enabled for `mod-list` or `mrpack` sources, staging may list unmanaged `.jar` files that would be deleted on apply. Apply is blocked until `advanced.allowRemoveUnmanagedMods` is `true` **and** `/msu stage confirm-destructive true` has been run on the active staged plan. ### Boot recovery and quarantine After a failed boot, automation and manual staging are blocked until `/msu boot clear-failure`. If an invalid staged plan is quarantined at apply time, acknowledge it with `/msu quarantine acknowledge` before staging again.

---

⚙️ Commands

Default command root: ```text /msu ``` All `/msu` commands require operator/admin permission. ### Command tree ```text /msu ├── status ├── reload ├── check │ ├── mods | server | self | all ├── stage │ ├── mods | server | self | all │ ├── confirm-destructive true | false │ └── cancel ├── rollback [backupId] ├── boot │ ├── clear-failure │ └── force-retry │ ├── current │ └── ├── quarantine │ ├── acknowledge │ └── delete confirm └── config ├── reset [param] └── set ├── source [path] ├── automation [targets] ├── interval ├── debug ├── server-maintenance ├── server-upgrade ├── mrpack-mode ├── release-channel [mod] ├── held └── required ``` ### Quick reference | Command | Purpose | | --- | --- | | `/msu status` | Show staged plan, runtime info, config, automation, rollback, unsafe-state warnings, and formatting state. | | `/msu reload` | Reload config from disk and restart automation. | | `/msu check mods` | Check configured mods for the **running** Minecraft version. | | `/msu check server` | Check server maintenance and optional **upgrade** readiness. | | `/msu check self` | Check for an MSU self-update. | | `/msu check all` | Run all configured checks (server, mods, and self sections as applicable). | | `/msu stage mods` | Stage mod updates for the **running** Minecraft version only. | | `/msu stage server` | Stage safe server maintenance or upgrade work. | | `/msu stage self` | Stage an MSU jar replacement. | | `/msu stage all` | Stage all safe selected targets into one combined plan. | | `/msu stage cancel` | Clear the staged plan. | | `/msu stage confirm-destructive true` / `false` | Acknowledge or clear destructive unmanaged mod removal on the active staged plan. | | `/msu rollback` | Restore the most recent apply backup. | | `/msu rollback ` | Restore a named backup. | | `/msu boot clear-failure` | Clear failed-boot record and boot failure streak (does not un-hold mods). | | `/msu boot force-retry current` | Allow automation to retry the current failed-update fingerprint. | | `/msu boot force-retry ` | Allow automation to retry a specific failed-update fingerprint. | | `/msu quarantine acknowledge` | Acknowledge a quarantined invalid staged plan so automation can continue. | | `/msu quarantine delete confirm` | Delete acknowledged quarantined evidence files. | | `/msu config reset` | Rewrite the config with documented defaults. | | `/msu config reset ` | Reset a specific config section (for example `source`, `release-channel`). | | `/msu config set …` | Change source, automation, interval, debug, server maintenance, upgrade, mrpack mode, release channel, held mods, or required mods. | Long-running checks may print to the server log; in RCON you may see a background notice — read `logs/latest.log` for full output.

---

🤖 Automation

MSU can run background checks on a timer. Automation modes: | Mode | Behaviour | | --- | --- | | `disabled` | No background activity. | | `check` | Report only; never stages files. | | `stage` | Checks and stages safe updates; you restart when ready. | | `install` | Checks, stages, then stops the server so the wrapper can apply updates on restart. | Automation targets: | Target | Purpose | | --- | --- | | `mods` | Check or stage configured mod source updates (running MC version). | | `server` | Check or stage Fabric server maintenance and optional Minecraft upgrades. | | `self` | Check or stage MSU self-update. | Example: ```text /msu config set automation stage server mods self /msu config set interval 360 ``` Use `install` only when the server is started through the wrapper and you are comfortable with MSU stopping the server for restart-based installation. Automation is blocked while a failed boot record is active, a quarantined invalid plan is pending acknowledgement, or a failed-update fingerprint has not been cleared or force-retried.

---

🚀 Quick start

1. Put the MSU jar in your server `mods/` folder. Modrinth releases use versioned names such as `minecraft-server-updater+fabric-26.1.2-0.2.0-beta.4.jar` — the filename changes when Minecraft or MSU version changes. 2. Configure your update source. 3. Run a check. 4. Stage available updates. 5. **Start the server from the server root** (where `fabric-server-launch.jar` lives) using the wrapper command below. ### Wrapper launcher scripts These are small launcher scripts which replace the existing start scripts in the server root. It picks the first `mods/minecraft-server-updater+fabric-*.jar` (or `mods/minecraft-server-updater.jar`) and runs the **same** wrapper command on every platform. **`start.bat` (Windows):** ```bat @echo off #set ram requirements here: set MC_XMX=2G set MC_XMS=2G cd /d "%~dp0" for %%F in ("mods\minecraft-server-updater+fabric-*.jar" "mods\minecraft-server-updater.jar") do ( java -jar "%%F" --wrap -- java -Xmx%MC_XMX% -Xms%MC_XMS% -jar fabric-server-launch.jar --nogui goto :after ) echo No Minecraft Server Updater jar found in mods\ pause exit /b 1 :after ``` **`start.sh` (Linux):** ```sh #!/usr/bin/env sh #set ram requirements here MC_XMX="${MC_XMX:-2G}" MC_XMS="${MC_XMS:-2G}" cd "$(dirname "$0")" || exit 1 for jar in mods/minecraft-server-updater+fabric-*.jar mods/minecraft-server-updater.jar; do if [ -f "$jar" ]; then exec java -jar "$jar" --wrap -- java -Xmx"$MC_XMX" -Xms"$MC_XMS" -jar fabric-server-launch.jar --nogui fi done echo "No Minecraft Server Updater jar found in mods/" exit 1 ``` On Linux: `chmod +x start.sh`, then `./start.sh`. ### Example manual update flow ```text /msu check mods /msu stage mods /msu status ``` Then restart with the wrapper (`start.bat`, `./start.sh`, or the `java -jar mods/minecraft-server-updater.jar …` line above). ### Example Minecraft upgrade flow ```text /msu config set server-upgrade latest /msu check server /msu stage all /msu status ``` Read `Server safe to stage` before staging — if it is `false`, fix the stated reason (often publish/install a target-compatible MSU build on Modrinth) before `stage all`.

---

📝 Example configuration

Config file: ```text config/minecraft-server-updater.json ``` Example shape: ```json { "debug": false, "mods": { "sourceType": "mod-list", "sourcePath": ".minecraft-server-updater/mod-list", "releaseChannel": "any" }, "server": { "maintenance": true, "upgrade": "off" }, "selfUpdate": { "enabled": true }, "automation": { "mode": "disabled", "intervalMinutes": 360, "targets": [] }, "advanced": { "unknownModPolicy": "error", "modUpgradePolicy": "warn", "readinessMode": "all", "mrpackMode": "exact", "preflightBeforeServerUpgrade": true } } ``` Common config commands: ```text /msu config set source mod-list /msu config set source mods-folder /msu config set source mrpack modpack.mrpack /msu config set server-maintenance on /msu config set server-upgrade latest /msu config set automation stage server mods self /msu config set mrpack-mode exact /msu config set debug on ``` If automation mode is `check`, `stage`, or `install` but `targets` is empty, automation runs with nothing to do until you add targets.

---

🎨 Console formatting

MSU includes styled output support for its own server-log lines. Advanced config: ```json "betterFabricConsoleFormatting": "auto" ``` Available values: | Value | Behaviour | | --- | --- | | `auto` | Default styled MSU output when console colour is allowed. | | `on` | Force styled MSU output when colour is allowed. | | `off` | Always use plain MSU server-log output. | If Better Fabric Console is installed separately, MSU avoids double-rendering and lets BFC handle Minecraft formatting.

---

❌ What MSU does not do

MSU is intentionally conservative. It does **not**: - Replace live jars while the server is running - Treat unknown/custom jars as Modrinth-managed projects - Apply staged updates without the wrapper - Magically verify compatibility for non-Modrinth files - Use fuzzy Modrinth search to resolve configured project names - Mix “routine mod updates on today’s version” with “server upgrade staging” in a single check — read server and mod sections separately

--- ## Recommended workflow **Routine mod updates (same Minecraft version):** ```text /msu check mods /msu stage mods /msu status ``` Restart with the wrapper when ready. **Planned Minecraft upgrade:** ```text /msu check server /msu check mods /msu stage all /msu status ``` Confirm `Server safe to stage: true` and review the combined plan before restart. **Scheduled staging:** ```text /msu config set automation stage mods /msu config set interval 360 ``` **Unattended install workflows:** ```text /msu config set automation install server mods self ``` Use install mode only when the server is started through the wrapper and you are happy for MSU to stop the server for restart-based installation. --- ## Why use MSU? MSU gives Fabric server owners a controlled update workflow: - See what needs updating before anything changes - Get clear reasons when staging is blocked - Stage files safely without touching live jars - Apply updates before boot through the wrapper - Keep server files and Modrinth-managed mods in sync - Automate routine checks - Recover with rollback support if an applied update causes problems

Septonious

Badges