This is an automated email from the ASF dual-hosted git repository.
jojochuang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/ozone-site.git
The following commit(s) were added to refs/heads/master by this push:
new 8040f9ca82 HDDS-16147. Document OM metadata backup including bucket
snapshots (#526)
8040f9ca82 is described below
commit 8040f9ca82b8170c024538373300dfed7fd8ca58
Author: Wei-Chiu Chuang <[email protected]>
AuthorDate: Fri Aug 28 20:33:05 2026 -0700
HDDS-16147. Document OM metadata backup including bucket snapshots (#526)
Generated-by: Cursor <[email protected]>
---
.../04-disk-replacement/01-ozone-manager.md | 2 +-
.../03-operations/11-tools/01-ozone-repair.md | 18 +++++-
.../01-om-metadata-backup.md | 75 ++++++++++++++++++++++
.../16-backup-and-recovery/README.mdx | 11 ++++
4 files changed, 104 insertions(+), 2 deletions(-)
diff --git
a/docs/05-administrator-guide/03-operations/04-disk-replacement/01-ozone-manager.md
b/docs/05-administrator-guide/03-operations/04-disk-replacement/01-ozone-manager.md
index 507dfd7602..f16a4556c3 100644
---
a/docs/05-administrator-guide/03-operations/04-disk-replacement/01-ozone-manager.md
+++
b/docs/05-administrator-guide/03-operations/04-disk-replacement/01-ozone-manager.md
@@ -49,7 +49,7 @@ This is a high-risk, manual disaster recovery process that
will require cluster
2. **Attempt Data Recovery:** If the failed disk is still partially readable,
make a best-effort attempt to copy the contents of the `ozone.om.db.dirs`
directory to a safe, temporary location.
-3. **If Recovery Fails, Restore from Backup:** If the OM database files are
unrecoverable, you must restore from your most recent backup. This document
does not cover the backup process itself, but it is the only path to recovery
in this scenario.
+3. **If Recovery Fails, Restore from Backup:** If the OM database files are
unrecoverable, restore from your most recent backup using [OM metadata
backup](../backup-and-recovery/om-metadata-backup#restore) (`ozone repair om
download`, or a saved tarball from the same command).
4. **Replace and Configure Disk:** Physically replace the hardware and ensure
the new, empty disk is mounted at the correct path defined in
`ozone.om.db.dirs`.
diff --git
a/docs/05-administrator-guide/03-operations/11-tools/01-ozone-repair.md
b/docs/05-administrator-guide/03-operations/11-tools/01-ozone-repair.md
index b687ef2103..9316b5306a 100644
--- a/docs/05-administrator-guide/03-operations/11-tools/01-ozone-repair.md
+++ b/docs/05-administrator-guide/03-operations/11-tools/01-ozone-repair.md
@@ -1,6 +1,6 @@
# Ozone Repair
-Ozone Repair (`ozone repair`) is an advanced tool to repair Ozone. The nodes
being repaired must be stopped before the tool is run.
+Ozone Repair (`ozone repair`) is an advanced tool to repair Ozone. Most
subcommands require the node being repaired to be stopped before the tool is
run. The `ozone repair om download` subcommand is an exception: it reads from a
**running** OM over HTTP(S) while you restore metadata onto a stopped node.
:::note
All repair commands support a `--dry-run` option which allows a user to see
what repair the command will be performing without actually making any changes
to the cluster.
@@ -69,6 +69,7 @@ Operational tool to repair OM.
- quota
- compact
- skip-ratis-transaction
+- download
### FSO-tree
@@ -229,6 +230,21 @@ from one of the good OMs to the crashing OM instead.
Path of the input segment file
```
+#### download
+
+Download OM metadata from a running OM (same v2 checkpoint flow as follower
bootstrap). The source cluster must be **running**; stop the target OM before
installing the output. Requires Ozone 2.2+ (HDDS-16171). See [OM metadata
backup](../backup-and-recovery/om-metadata-backup).
+
+```bash
+Usage: ozone repair om download [-hV] [--dry-run] [--overwrite] [--verbose]
+ [--node-id=<nodeId>]
+ [--om-service-id=<omServiceId>]
+ --output-dir=<outputDir>
+ --node-id=<nodeId> OM node to download from (recommended:
leader)
+ --om-service-id, --service-id Ozone Manager Service ID
+ --output-dir=<outputDir> Output directory (om.db and db.snapshots)
+ --overwrite Overwrite output directory if it exists
+```
+
## ozone repair SCM
Operational tool to repair SCM.
diff --git
a/docs/05-administrator-guide/03-operations/16-backup-and-recovery/01-om-metadata-backup.md
b/docs/05-administrator-guide/03-operations/16-backup-and-recovery/01-om-metadata-backup.md
new file mode 100644
index 0000000000..9629d5d119
--- /dev/null
+++
b/docs/05-administrator-guide/03-operations/16-backup-and-recovery/01-om-metadata-backup.md
@@ -0,0 +1,75 @@
+---
+sidebar_label: OM metadata backup
+---
+
+# OM metadata backup (including bucket snapshots)
+
+Back up **Ozone Manager (OM) namespace metadata**, including **bucket
snapshot** RocksDB state, with `ozone repair om download`
([HDDS-16171](https://issues.apache.org/jira/browse/HDDS-16171)). This is not a
substitute for Datanode block or SCM metadata backups.
+
+The command uses the same v2 checkpoint transfer as OM follower bootstrap
([design
doc](../../../system-internals/features/om-bootstrapping-with-snapshots)). It
handles multi-batch download and hard link reconstruction, and writes a
ready-to-install tree under `--output-dir`.
+
+Requires Ozone **2.2+** with HDDS-16171.
+
+## What is included
+
+- `om.db` — volumes, buckets, keys, and related AOS metadata
+- `db.snapshots` — bucket snapshot RocksDB state (when snapshots exist on the
leader)
+- Compaction backup and log directories needed to read snapshot SST files
+
+## Backup
+
+**Requirements:** `ozone-site.xml` on the host; `kinit` in secure clusters
(`ozone.administrators`).
+
+```shell
+ozone repair om download --output-dir /backup/om-metadata --overwrite
+
+# OM HA — add --service-id; --node-id targets a specific OM (leader
recommended)
+ozone repair om download \
+ --service-id <om-service-id> \
+ --node-id <om-node-id> \
+ --output-dir /backup/om-metadata \
+ --overwrite
+
+tar -czf om-metadata-$(date +%Y%m%d).tar.gz -C /backup om-metadata
+```
+
+Store archives off-cluster according to your retention policy.
+
+## Restore
+
+Stop the **target** OM before installing metadata. If a live OM is still up,
re-run `ozone repair om download`. Otherwise extract a saved archive:
+
+```shell
+mkdir -p /restore
+tar -xzf om-metadata-YYYYMMDD.tar.gz -C /restore
+
+OM_DB_DIRS=/var/lib/ozone/om/metadata
+rm -rf "$OM_DB_DIRS/om.db" "$OM_DB_DIRS/db.snapshots"
+rsync -a /restore/om-metadata/ "$OM_DB_DIRS/"
+
+# Start OM; verify with: ozone sh volume list
+```
+
+For HA with an intact Ratis ring, prefer `ozone om --bootstrap` over manual
install. See [Replacing Ozone Manager disks](../disk-replacement/ozone-manager)
and [Ozone Repair](../tools/ozone-repair#download).
+
+## Operational notes
+
+- When using `--node-id`, target the **leader** OM.
+- Schedule backups during low snapshot activity; including snapshot data takes
a short-lived cache lock.
+- Do **not** use Recon as a backup source (`includeSnapshotData=false` by
design).
+- User-visible **Ozone Snapshots** are included. **Ratis snapshots** (OM HA
replication) are a separate concept — see [OM high
availability](../../../system-internals/components/ozone-manager/high-availability).
+
+## Related configuration
+
+| Property | Default | Relevance |
+| ---------- | --------- | --------- |
+| `ozone.om.db.checkpoint.use.inode.based.transfer` | `true` | Required for
snapshot-inclusive backup |
+| `ozone.administrators` | (none) | CLI access in secure mode |
+
+## See also
+
+- [OM bootstrapping with snapshots
(design)](../../../system-internals/features/om-bootstrapping-with-snapshots)
+- [OM HA configuration](../../configuration/high-availability/om-ha)
+- [Replacing Ozone Manager disks](../disk-replacement/ozone-manager)
+- [Troubleshooting OM HA snapshot
installation](../../../troubleshooting/om-ha-snapshot-installation-issues)
+- [Snapshots overview](../snapshots/overview)
diff --git
a/docs/05-administrator-guide/03-operations/16-backup-and-recovery/README.mdx
b/docs/05-administrator-guide/03-operations/16-backup-and-recovery/README.mdx
new file mode 100644
index 0000000000..c518ac0767
--- /dev/null
+++
b/docs/05-administrator-guide/03-operations/16-backup-and-recovery/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Backup and recovery
+---
+
+# Backup and recovery
+
+import DocCardList from '@theme/DocCardList';
+
+Operator procedures for backing up Ozone metadata and related
disaster-recovery planning.
+
+<DocCardList/>
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
