RADOSGW-ADMIN(8)

📦
version 20.2.4 · 20 versions
, in ubuntu stonking

🦋 radosgw-admin(8) — Ceph 🦋

okay so bestie, this is the manual for radosgw-admin from Ceph. it's giving admin tool realness, and we're about to get into it. 💅

✨ NAME ✨

radosgw-admin — rados REST gateway user administration utility. no cap.

🎀 SYNOPSIS 🎀

radosgw-admin command [ options ... ]

🌈 DESCRIPTION 🌈

radosgw-admin is a Ceph Object Gateway user administration utility. It is used to create and modify users. periodt. 💖

👑 COMMANDS 👑

The radosgw-admin utility provides commands for administration purposes as follows:

  • user create — Create a new user. ✨
  • user modify — Modify a user. 💅
  • user info — Display information for a user including any subusers and keys. 👀
  • user rename — Renames a user. ✏️
  • user rm — Remove a user. 💀
  • user suspend — Suspend a user. 😭
  • user enable — Re-enable user after suspension. 🫶
  • user check — Check user info. 🔍
  • user stats — Show user stats as accounted by the quota subsystem. 📊
  • user list — List all users. 👥
  • caps add — Add user capabilities. 👑
  • caps rm — Remove user capabilities. 🙈
  • subuser create — Create a new subuser (primarily useful for clients using the Swift API). 🦋
  • subuser modify — Modify a subuser. 💅
  • subuser rm — Remove a subuser. 💀
  • key create — Create access key. 🔑
  • key rm — Remove access key. 🗑️
  • bucket list — List buckets, or, if a bucket is specified with --bucket=<bucket>, list its objects. Adding --allow-unordered removes the ordering requirement, possibly generating results more quickly for buckets with large number of objects. 🪣
  • bucket limit check — Show bucket sharding stats. 📈
  • bucket link — Link bucket to specified user. 🔗
  • bucket unlink — Unlink bucket from specified user. ✂️
  • bucket chown — Change bucket ownership to the specified user and update object ACLs. Invoke with --marker to resume if the command is interrupted. 👑
  • bucket stats — List bucket statistics plus other internal information about a bucket. 📊
  • bucket rm — Remove a bucket. 💀
  • bucket check — Check bucket index. 🔍
  • bucket rewrite — Rewrite all objects in the specified bucket. ♻️
  • bucket radoslist — List the RADOS objects that contain the data for all objects in the designated bucket, if --bucket=<bucket> is specified. Otherwise, list the RADOS objects that contain data for all buckets. 📋
  • bucket reshard — Reshard a bucket's index. 🧩
  • bucket sync disable — Disable bucket sync. 🚫
  • bucket sync enable — Enable bucket sync. ✅
  • bi get — Retrieve bucket index object entries. 📥
  • bi put — Store bucket index object entries. 📤
  • bi list — List raw bucket index entries. 📝
  • bi purge — Purge bucket index entries. 🔥
  • object rm — Remove an S3/Swift object. Include --yes-i-really-mean-it to remove object's entry from bucket index, for example if it's damaged. 💀
  • object stat — Stat an S3/Swift object for its metadata. 🔍
  • object manifest — Display the manifest of an S3/Swift object, producing a list of RADOS objects containing the data. 📜
  • object unlink — Unlink S3/Swift object from bucket index. ✂️
  • object rewrite — Rewrite the specified S3/Swift object. ♻️
  • object reindex — Add an S3/Swift object to its bucket's index. Used rarely for emergency repairs. 🚑
  • objects expire — Run expired objects cleanup. 🧹
  • period rm — Remove a period. 💀
  • period get — Get the period info. 📅
  • period get-current — Get the current period info. 🕒
  • period pull — Pull a period. 📥
  • period push — Push a period. 📤
  • period list — List all periods. 📋
  • period update — Update the staging period. 🔄
  • period commit — Commit the staging period. ✅
  • quota set — Set quota params. ⚙️
  • quota enable — Enable quota. ✅
  • quota disable — Disable quota. 🚫
  • global quota get — View global quota parameters. 🌍
  • global quota set — Set global quota parameters. ⚙️
  • global quota enable — Enable a global quota. ✅
  • global quota disable — Disable a global quota. 🚫
  • realm create — Create a new realm. 🌌
  • realm rm — Remove a realm. 💀
  • realm get — Show the realm info. ℹ️
  • realm get-default — Get the default realm name. 🎯
  • realm list — List all realms. 📋
  • realm list-periods — List all realm periods. 📅
  • realm rename — Rename a realm. ✏️
  • realm set — Set the realm info (requires infile). 📝
  • realm default — Set the realm as default. 👑
  • realm pull — Pull a realm and its current period. 📥
  • zonegroup add — Add a zone to a zonegroup. ➕
  • zonegroup create — Create a new zone group info. 🏗️
  • zonegroup default — Set the default zone group. 👑
  • zonegroup rm — Remove a zone group info. 💀
  • zonegroup get — Show the zone group info. ℹ️
  • zonegroup modify — Modify an existing zonegroup. ✏️
  • zonegroup set — Set the zone group info (requires infile). 📝
  • zonegroup remove — Remove a zone from a zonegroup. ➖
  • zonegroup rename — Rename a zone group. ✏️
  • zonegroup list — List all zone groups set on this cluster. 📋
  • zonegroup placement list — List zonegroup's placement targets. 📍
  • zonegroup placement add — Add a placement target id to a zonegroup. ➕
  • zonegroup placement modify — Modify a placement target of a specific zonegroup. ✏️
  • zonegroup placement rm — Remove a placement target from a zonegroup. ➖
  • zonegroup placement default — Set a zonegroup's default placement target. 👑
  • zone create — Create a new zone. 🌍
  • zone rm — Remove a zone. 💀
  • zone get — Show zone cluster params. ℹ️
  • zone set — Set zone cluster params (requires infile). 📝
  • zone modify — Modify an existing zone. ✏️
  • zone list — List all zones set on this cluster. 📋
  • metadata sync status — Get metadata sync status. 🔄
  • metadata sync init — Init metadata sync. 🚀
  • metadata sync run — Run metadata sync. 🏃
  • data sync status — Get data sync status of the specified source zone. 🔄
  • data sync init — Init data sync for the specified source zone. 🚀
  • data sync run — Run data sync for the specified source zone. 🏃
  • sync error list — List sync errors. ⚠️
  • sync error trim — Trim sync errors. ✂️
  • zone rename — Rename a zone. ✏️
  • zone placement list — List a zone's placement targets. 📍
  • zone placement add — Add a zone placement target. ➕
  • zone placement modify — Modify a zone placement target. ✏️
  • zone placement rm — Remove a zone placement target. ➖
  • pool add — Add an existing pool for data placement. 🏊
  • pool rm — Remove an existing pool from data placement set. 💀
  • pools list — List placement active set. 📋
  • policy — Display bucket/object policies (e.g. permissions/ACLs etc.). 📜
  • log list — List log objects. 📋
  • log show — Dump a log from specific object or (bucket + date + bucket-id). (NOTE: required to specify formatting of date to "YYYY-MM-DD-hh"). 🪵
  • log rm — Remove log object. 🗑️
  • usage show — Show the usage information (with optional user and date range). 📊
  • usage trim — Trim usage information (with optional user and date range). ✂️
  • gc list — Dump expired garbage collection objects (specify --include-all to list all entries, including unexpired). 🗑️
  • gc process — Manually process garbage. ♻️
  • lc get — Get lifecycle config for a bucket. 🔄
  • lc list — List all bucket lifecycle progress. 📋
  • lc process — Manually process lifecycle transitions. If a bucket is specified (e.g., via --bucket_id or via --bucket and optional --tenant), only that bucket is processed. 🔄
  • metadata get — Get metadata info. ℹ️
  • metadata put — Put metadata info. 📤
  • metadata rm — Remove metadata info. 💀
  • metadata list — List metadata info. 📋
  • mdlog list — List metadata log which is needed for multi-site deployments. 📋
  • mdlog trim — Trim metadata log manually instead of relying on the gateway's integrated log sync. Before trimming, compare the listings and make sure the last sync was complete, otherwise it can reinitiate a sync. ✂️
  • mdlog status — Read metadata log status. 📊
  • bilog list — List bucket index log which is needed for multi-site deployments. 📋
  • bilog trim — Trim bucket index log (use start-marker, end-marker) manually instead of relying on the gateway's integrated log sync. Before trimming, compare the listings and make sure the last sync was complete, otherwise it can reinitiate a sync. ✂️
  • datalog list — List data log which is needed for multi-site deployments. 📋
  • datalog trim — Trim data log manually instead of relying on the gateway's integrated log sync. Before trimming, compare the listings and make sure the last sync was complete, otherwise it can reinitiate a sync. ✂️
  • datalog status — Read data log status. 📊
  • orphans find — Init and run search for leaked RADOS objects. DEPRECATED. See the rgw-orphan-list tool. ⚠️
  • orphans finish — Clean up search for leaked RADOS objects. DEPRECATED. See the rgw-orphan-list tool. ⚠️
  • orphans list-jobs — List the current orphans search job IDs. DEPRECATED. See the rgw-orphan-list tool. ⚠️
  • role create — Create a new role for use with STS (Security Token Service). 🎭
  • role rm — Remove a role. 💀
  • role get — Get a role. 📥
  • role list — List the roles with specified path prefix. 📋
  • role modify — Modify the assume role policy of an existing role. ✏️
  • role-policy put — Add/update permission policy to role. ➕
  • role-policy list — List the policies attached to a role. 📋
  • role-policy get — Get the specified inline policy document embedded with the given role. 📄
  • role-policy rm — Remove the policy attached to a role. 💀
  • reshard add — Schedule a resharding of a bucket. 📅
  • reshard list — List all bucket resharding or scheduled to be resharded. 📋
  • reshard process — Process of scheduled reshard jobs. ⚙️
  • reshard status — Resharding status of a bucket. 📊

part 1 done, more coming 💖

  • reshard cancel — nope, we're not resharding that bucket anymore, cancel it 💅
  • topic list — lists out all your bucket notification topics ✨
  • topic get — grabs one bucket notification topic for you 🎀
  • topic rm — deletes a bucket notifications topic, bye bestie 👋
  • topic stats — shows the persistent topic stats for bucket notifications, aka reservations, entries and size 🔥
  • topic dump — dumps (in JSON, bestie, it's giving structured data ✨) all the pending bucket notifications of a persistent topic

✨ OPTIONS ✨

Okay so this is the big one, the options buffet, the main character section, let's go 🫶

  • -c ceph.conf, --conf=ceph.conf — use this ceph.conf config file instead of the default /etc/ceph/ceph.conf when it's figuring out monitor addresses at startup 💖
  • -m monaddress[:port] — connect to this specific monitor instead of letting it pick one out of ceph.conf 👑
  • --tenant=<tenant> — the name of the tenant 🏠
  • --uid=uid — the user you're operating on, that's the one 💅
  • --new-uid=uid — the new ID of the user. this one rides along with the user rename command ✨
  • --subuser=<name> — the name of the subuser 🎀
  • --access-key=<key> — the S3 access key 🔑
  • --email=email — the user's e-mail address, yes we're collecting those 📧
  • --secret/--secret-key=<key> — the secret key, shhh 🤫
  • --gen-access-key — generates a random access key (for S3) 🎲
  • --gen-secret — generates a random secret key 🎲
  • --generate-key — create a user with or without credentials. here's the deal: if this is set to false, then the user cannot set --gen-access-key/--gen-secret/--secret-key/--access-key. if it's set to true, then the user cannot set --secret-key/--access-key and instead bypasses those options in favor of --gen-secret/--gen-access-key. default is true 👑
  • --key-type=<type> — the key type, and your options are swift and s3 💖
  • --temp-url-key[-2]=<key> — the temporary URL key ⏳
  • --max-buckets — max number of buckets a user can have (0 means no limit at all, and a negative value disables bucket creation entirely, no cap fr). default is 1000 🌸
  • --access=<access> — sets the access permissions for the subuser. available ones are read, write, readwrite and full ✅
  • --display-name=<name> — the display name of the user ✨
  • --admin — sets the admin flag on the user 👑
  • --system — sets the system flag on the user 🌈
  • --bucket=[tenant-id/]bucket — specify the bucket name. and if you don't give a tenant-id, it just uses the tenant-id of the user (--uid) 🪣
  • --pool=<pool> — specify the pool name. it's also used with orphans find as the data pool to scan for leaked rados objects 🔍
  • --object=object — specify the object name 📦
  • --date=yyyy-mm-dd — a date in the format yyyy-mm-dd 📅
  • --start-date=yyyy-mm-dd — the start date in the format yyyy-mm-dd 📅
  • --end-date=yyyy-mm-dd — the end date in the format yyyy-mm-dd 📅
  • --bucket-id=<bucket-id> — specify the bucket id 🆔
  • --bucket-new-name=[tenant-id/]<bucket> — optional for bucket link, use it to rename a bucket. and yeah you can specify the tenant-id, but honestly you don't need to in normal operation 💅
  • --shard-id=<shard-id> — optional for mdlog list, bi list and data sync status. required for mdlog trim ⚠️
  • --max-entries=<entries> — optional, for listing operations, to say the max entries you want 📋
  • --purge-data — when you set this, removing the user also purges that user's data 💀 (dramatic but yes)
  • --purge-keys — when you set this, removing the subuser also purges the subuser's keys 🔑
  • --purge-objects — when you set this, removing the bucket also purges every object inside it 💀
  • --metadata-key=<key> — the key to retrieve metadata from, used with metadata get 🔍
  • --remote=<remote> — zone or zonegroup id of the remote gateway 🌐
  • --period=<id> — the period ID 📆
  • --url=<url> — the URL for pushing/pulling a period or realm 🔗
  • --epoch=<number> — the period epoch 🔢
  • --commit — commit the period during period update ✅
  • --staging — get the staging period info 🎭
  • --master — set as master 👑
  • --master-zone=<id> — the master zone ID 🏰
  • --rgw-realm=<name> — the realm name ✨
  • --realm-id=<id> — the realm ID 🆔
  • --realm-new-name=<name> — a new name for the realm 🏷️
  • --rgw-zonegroup=<name> — the zonegroup name 🌍
  • --zonegroup-id=<id> — the zonegroup ID 🆔
  • --zonegroup-new-name=<name> — the new name of the zonegroup 🏷️
  • --rgw-zone=<zone> — the zone in which the gateway is running 🏃
  • --zone-id=<id> — the zone ID 🆔
  • --zone-new-name=<name> — the new name of the zone 🏷️
  • --source-zone — the source zone for data sync 📡
  • --default — set the entity (realm, zonegroup, zone) as default ⭐
  • --read-only — set the zone as read-only when adding it to the zonegroup 🔒
  • --placement-id — placement ID for the zonegroup placement commands 📍
  • --tags=<list> — the list of tags for zonegroup placement add and modify commands 🏷️
  • --tags-add=<list> — the list of tags to add for the zonegroup placement modify command ➕
  • --tags-rm=<list> — the list of tags to remove for the zonegroup placement modify command ➖
  • --endpoints=<list> — the zone endpoints 🌐
  • --index-pool=<pool> — the placement target index pool 🗂️
  • --data-pool=<pool> — the placement target data pool 💾
  • --data-extra-pool=<pool> — the placement target data extra (non-EC) pool 💾
  • --placement-index-type=<type> — the placement target index type, so normal, indexless, or #id 🗂️
  • --placement-inline-data=<true> — whether the placement target is configured to store a data chunk inline in head objects 🧩
  • --tier-type=<type> — the zone tier type 🏗️
  • --tier-config=<k>=<v>[,...] — set zone tier config keys and values ⚙️
  • --tier-config-rm=<k>[,...] — unset zone tier config keys 🗑️
  • --sync-from-all[=false] — set/reset whether the zone syncs from all zonegroup peers 🔄
  • --sync-from=[zone-name][,...] — set the list of zones to sync from 📥
  • --sync-from-rm=[zone-name][,...] — remove zone(s) from the list of zones to sync from 📤
  • --bucket-index-max-shards — override a zone's or zonegroup's default number of bucket index shards. this option is accepted by the zone create, zone modify, zonegroup add, and zonegroup modify commands, and it applies to buckets that are created after the zone/zonegroup changes take effect ✨
  • --fix — fix the bucket index in addition to checking it 🔧
  • --check-objects — bucket check: rebuilds the bucket index according to the actual object state 🔍
  • --format=<format> — specify the output format for certain operations. supported formats: xml, json 🎀
  • --sync-stats — an option for the user stats command. when you set it, it updates user stats with the current stats reported by the user's bucket indexes 📊
  • --show-config — show configuration ⚙️
  • --show-log-entries=<flag> — enable/disable dumping of log entries on log show 📜
  • --show-log-sum=<flag> — enable/disable dumping of log summation on log show 📜
  • --skip-zero-entries — log show only dumps entries that don't have a zero value in one of the numeric fields 🙈
  • --infile — specify a file to read when setting data 📄
  • --categories=<list> — comma separated list of categories, used in usage show 🗂️
  • --caps=<caps> — list of capabilities (e.g., "usage=read, write; user=read") 💪
  • --compression=<compression-algorithm> — placement target compression algorithm, so lz4, snappy, zlib, or zstd 🗜️
  • --yes-i-really-mean-it — required as a guardrail for certain destructive operations 🚨 (yeah she's for real for real)
  • --min-rewrite-size — specify the minimum object size for bucket rewrite (default 4M) 📏
  • --max-rewrite-size — specify the maximum object size for bucket rewrite (default ULLONG_MAX) 📏
  • --min-rewrite-stripe-size — specify the minimum stripe size for object rewrite (default 0). and if the value is set to 0, then the specified object will always be rewritten when restriping 💅
  • --warnings-only — when specified with bucket limit check, it lists only the buckets nearing or over the current max objects per shard value ⚠️
  • --bypass-gc — when specified with bucket deletion, it triggers object deletion without involving GC 💀
  • --inconsistent-index — when specified with bucket deletion and bypass-gc set to true, it ignores bucket index consistency 🙈
  • --max-concurrent-ios — maximum concurrent bucket operations. this affects operations that scan the bucket index, e.g., listing, deletion, and all scan/search operations such as finding orphans or checking the bucket index. the default is 32 🚀

💖 QUOTA OPTIONS 💖

  • --max-objects — specify the maximum number of objects (a negative value disables it) 🔢
  • --max-size — specify the maximum object size (in B/K/M/G/T, negative value disables it) 📏
  • --quota-scope — the scope of the quota, so bucket or user 🎯

🔍 ORPHANS SEARCH OPTIONS 🔍

  • --num-shards — number of shards to use for temporary scan info 🧩
  • --orphan-stale-secs — number of seconds to wait before declaring an object to be an orphan. the default is 86400 (24 hours) ⏰
  • --job-id — set the job id (for orphans find) 🆔

📋 ORPHANS LIST-JOBS OPTIONS 📋

  • --extra-info — provide extra info in the job list 📝

👑 ROLE OPTIONS 👑

  • --role-name — the name of the role to create ✨
  • --path — the path to the role 📁
  • --assume-role-policy-doc — the trust relationship policy document that grants an entity permission to assume the role 🤝
  • --policy-name — the name of the policy document 📜
  • --policy-doc — the permission policy document 📜
  • --path-prefix — the path prefix for filtering the roles 🗂️

🦋 BUCKET NOTIFICATIONS/PUBSUB OPTIONS 🦋

  • --topic — the bucket notifications/pubsub topic name ✨
  • --subscription — the pubsub subscription name 📬
  • --event-id — the event id in a pubsub subscription 🆔

✨ EXAMPLES ✨

okay bestie this is the part where it all comes together, the little recipe book of "here's literally exactly what you type" 💖 every single one of these is copy-paste-able, so go off.

Make a new user, iconic:

$ radosgw-admin user create --display-name="johnny rotten" --uid=johnny
{ "user_id": "johnny",
  "rados_uid": 0,
  "display_name": "johnny rotten",
  "email": "",
  "suspended": 0,
  "subusers": [],
  "keys": [
        { "user": "johnny",
          "access_key": "TCICW53D9BQ2VGC46I44",
          "secret_key": "tfm9aHMI8X76L3UdgE+ZQaJag1vJQmE6HDb5Lbrz"}],
  "swift_keys": []}

look at those keys bestie, that's the whole glow-up right there 🔑✨

Yeet a user:

$ radosgw-admin user rm --uid=johnny

Give a user a whole new name, main character rebrand:

$ radosgw-admin user rename --uid=johnny --new-uid=joe

Remove a user AND every single bucket they own with all the stuff inside it:

$ radosgw-admin user rm --uid=johnny --purge-data
⚠️ bestie be so for real before you run this one, --purge-data is not playing around, the data is gone gone 💀

Remove a bucket:

$ radosgw-admin bucket rm --bucket=foo

Link a bucket to a specific user (yes you need the bucket id, it's giving very specific):

$ radosgw-admin bucket link --bucket=foo --bucket_id=<bucket id> --uid=johnny

Unlink a bucket from a user, it's not theirs anymore, we're detaching:

$ radosgw-admin bucket unlink --bucket=foo --uid=johnny

Rename a bucket, sneaky little slay:

$ radosgw-admin bucket link --bucket=foo --bucket-new-name=bar --uid=johnny

Move a bucket from the old global tenant space over to a specified tenant, lowkey a relocation arc:

$ radosgw-admin bucket link --bucket=foo --uid='12345678$12345678'

Link a bucket to a specified user AND change the object ACLs at the same time, multitasking queen:

$ radosgw-admin bucket chown --bucket=foo --uid='12345678$12345678'

Show a bucket's logs from April 1st, 2012:

$ radosgw-admin log show --bucket=foo --date=2012-04-01-01 --bucket-id=default.14193.1

Show usage info for a user from March 1st up to but NOT including April 1st, 2012 (the boundary is exclusive, keep that in mind bestie):

$ radosgw-admin usage show --uid=johnny \
                --start-date=2012-03-01 --end-date=2012-04-01

Show ONLY the summary of usage info for all the users, no log entries, we're keeping it cute and concise:

$ radosgw-admin usage show --show-log-entries=false

Trim the usage information for a user until March 1st, 2012:

$ radosgw-admin usage trim --uid=johnny --end-date=2012-04-01

🌈 AVAILABILITY 🌈

so radosgw-admin is part of Ceph, which is a massively scalable, open-source, distributed storage system (yes, the whole flex 💅). if you want more info, please refer to the Ceph documentation at <https://docs.ceph.com>. go read it, it's good for you 🫶

👀 SEE ALSO 👀

  • ceph <>(8)
  • radosgw <>(8)

2010-2014, Inktank Storage, Inc. and contributors. Licensed under Creative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0).

and that's the whole page bestie, you made it to the end, I'm so proud of you 🥹💖 this was dev on Oct 06, 2026, filed under RADOSGW-ADMIN(8). now go create some users and slay responsibly ✨👑

📦 where this page comes from