{"id":51874063,"url":"https://github.com/vbrik/ceph-tools","last_synced_at":"2026-07-25T04:30:30.082Z","repository":{"id":371609846,"uuid":"1297811445","full_name":"vbrik/ceph-tools","owner":"vbrik","description":"Miscellaneous Ceph Tools","archived":false,"fork":false,"pushed_at":"2026-07-15T20:56:20.000Z","size":55,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-07-15T22:27:34.860Z","etag":null,"topics":["ceph","ceph-cluster","cephfs"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vbrik.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-11T22:06:15.000Z","updated_at":"2026-07-15T20:56:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vbrik/ceph-tools","commit_stats":null,"previous_names":["vbrik/ceph-tools"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/vbrik/ceph-tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vbrik%2Fceph-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vbrik%2Fceph-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vbrik%2Fceph-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vbrik%2Fceph-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vbrik","download_url":"https://codeload.github.com/vbrik/ceph-tools/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vbrik%2Fceph-tools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35866686,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-25T02:00:06.922Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ceph","ceph-cluster","cephfs"],"created_at":"2026-07-25T04:30:29.519Z","updated_at":"2026-07-25T04:30:30.073Z","avatar_url":"https://github.com/vbrik.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ceph-tools\n\nCommand-line tools for Ceph and CephFS cluster administration, debugging,\nand troubleshooting: PG movement/remapping, OSD/PG lookups, MDS ops\ninspection, CephFS client load and inode-to-path resolution. Each tool\nwraps `ceph` CLI / `rados` output (mostly JSON) into something more\ndirectly useful — grouping, resolving IDs to names, diffing, sorting — for\nquestions that come up repeatedly during cluster operation but aren't\nanswered directly by a single `ceph` subcommand.\n\nEvery script is standalone and can be copied out and run on its own; there\nis no shared library or install step beyond the requirements below.\n\n## Requirements\n\n- A working `ceph` CLI (and `rados`, `ceph-dencoder` for a couple of tools)\n  pointed at the target cluster.\n- Python 3 for the `.py` scripts (`cephfs-client-inodes.py` runs under the\n  `python` shebang, everything else under `python3`). Stdlib only, except:\n  - `cephfs-mds-ops-pretty.py` can optionally resolve UID/GID to names via\n    LDAP, using the `ldap3` package if installed, falling back to the\n    `ldapsearch` CLI otherwise. This is off by default and only activates\n    when both `--ldap-server` and `--ldap-base` are given (see `--help`).\n- `jq` for the `.sh` scripts.\n- `getfattr` (from `attr`/`acl` packages) for `cephfs-du`.\n\nSome scripts hard-code environment-specific defaults (e.g. pool names\n`cephfs.default.meta`/`cephfs.default.data`) that were written for a\nspecific cluster. Check `--help` and adjust flags/defaults as needed for\nother environments.\n\n## Tools\n\n### RADOS / OSD\n\n- **`ceph-show-osds-of-pg`** — Show the `up` and `acting` OSD sets for a\n  given PG, with each OSD's host.\n  `ceph-show-osds-of-pg \u003cpgid\u003e`\n\n- **`ceph-show-pg-movements.py`** — For every PG where `up` != `acting`,\n  print source/destination OSDs, movement type, and PG state. Handles EC\n  (per-shard) and replicated (set-diff) pools differently; see\n  `--help` for the full explanation of the diffing logic and edge cases.\n  `ceph-show-pg-movements.py [--sort-by {pgid,from-osd,to-osd}]`\n\n- **`ceph-show-upmaps-of-osd.sh`** — Show `pg_upmap_items` entries where a\n  given OSD is a source or destination.\n  `ceph-show-upmaps-of-osd.sh \u003cosd\u003e`\n\n- **`cephfs-find-large-omap-objects.sh`** — List PGs with objects flagged\n  for having large omap entries.\n\n- **`pgremapper`** (git submodule, [digitalocean/pgremapper](https://github.com/digitalocean/pgremapper)) —\n  Third-party tool for controlling PG backfill/remapping without CRUSH map\n  changes. Run `git submodule update --init` and build per its own README.\n\n### CephFS clients and MDS\n\n- **`cephfs-client-id-to-host`** — Resolve a CephFS client session ID to\n  hostname and IP.\n  `cephfs-client-id-to-host \u003cclient-id\u003e`\n\n- **`cephfs-client-inodes.py`** — Show filesystem paths for the inodes\n  (delegated/completed-request/preallocated) held by a client session.\n  Reads client sessions from a `client ls` JSON file/stdin, or, if the file\n  argument is omitted, queries MDS rank(s) live via\n  `ceph tell mds.RANK client ls` (all active ranks by default, or one rank\n  via `--rank`); live queries print a warning since `client ls` can be\n  resource-intensive on a busy MDS.\n  `cephfs-client-inodes.py [--meta-pool POOL] [--data-pool POOL] [--rank RANK] \u003cclient\u003e [file|-]`\n\n- **`cephfs-client-load-top.py`** — `top`-style live view of CephFS client\n  load across MDS ranks (request rate, caps, leases, in-flight requests,\n  etc.), sortable and filterable by column, with optional result caching.\n  `cephfs-client-load-top.py [-r RANK] [-n N] [-s COLUMNS] [--hide COLUMNS] [--cache-ttl SECONDS] [--cache-file PATH] [--full-mount-point]`\n\n- **`cephfs-mds-ops-pretty.py`** — Human-friendly rendering of\n  `ceph tell mds.X dump_{blocked,historic,ops_in_flight}` JSON. By default,\n  auto-detects and queries every active MDS rank live, tagging each op with\n  its rank (`--mds-rank` restricts to one); a saved JSON file can be used\n  instead via `--json-file`. Resolves inodes to paths and client IDs to\n  hostnames/users.\n  Inode-to-path lookups are cached on disk across runs by default (see\n  `--inode-cache-ttl`/`--no-inode-cache`/`--inode-cache-dir` in `--help`).\n  `client ls` results are cached the same way for a short time by default\n  (10 minutes), since a stale cache can hide the very client generating the\n  op you're inspecting (see `--client-cache-ttl`/`--client-cache-file`).\n  `cephfs-mds-ops-pretty.py dump_ops_in_flight [options]`\n\n- **`cephfs-dir-tree-pins.sh`** — List directories pinned (exported) to\n  each MDS rank.\n\n- **`cephfs-inode-to-path`** — Resolve a hex inode number to its filesystem\n  path via the metadata/data pool backtrace xattr.\n  `cephfs-inode-to-path \u003cinode-hex\u003e`\n\n- **`cephfs-du`** — Report size (`ceph.dir.rbytes` for directories, file\n  size otherwise) of paths on a mounted CephFS, in human-readable units.\n  `cephfs-du \u003cpath\u003e [path...]`\n\n## License\n\nMIT (see `LICENSE`). `pgremapper` (submodule) carries its own Apache 2.0\nlicense.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvbrik%2Fceph-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvbrik%2Fceph-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvbrik%2Fceph-tools/lists"}