Scroll to navigation



radosgw-admin - rados REST gateway user administration utility


radosgw-admin command [ options ... ]


radosgw-admin is a RADOS gateway user administration utility. It allows creating and modifying users.


radosgw-admin utility uses many commands for administration purpose which are as follows:

Create a new user.
Modify a user.
Display information of a user, and any potentially available subusers and keys.
Renames a user.
Remove a user.
Suspend a user.
Re-enable user after suspension.
Check user info.
Show user stats as accounted by quota subsystem.
List all users.
Add user capabilities.
Remove user capabilities.
Create a new subuser (primarily useful for clients using the Swift API).
Modify a subuser.
Remove a subuser.
Create access key.
Remove access key.
List buckets, or, if bucket specified with --bucket=<bucket>, list its objects. If bucket specified adding --allow-unordered removes ordering requirement, possibly generating results more quickly in buckets with large number of objects.
Show bucket sharding stats.
Link bucket to specified user.
Unlink bucket from specified user.
Link bucket to specified user and update object ACLs. Use --marker to resume if command gets interrupted.
Returns bucket statistics.
Remove a bucket.
Check bucket index.
Rewrite all objects in the specified bucket.
List the rados objects that contain the data for all objects is the designated bucket, if --bucket=<bucket> is specified, or otherwise all buckets.
Reshard a bucket.
Disable bucket sync.
Enable bucket sync.
Retrieve bucket index object entries.
Store bucket index object entries.
List raw bucket index entries.
Purge bucket index entries.
Remove an object.
Stat an object for its metadata.
Unlink object from bucket index.
Rewrite the specified object.
Run expired objects cleanup.
Remove a period.
Get the period info.
Get the current period info.
Pull a period.
Push a period.
List all periods.
Update the staging period.
Commit the staging period.
Set quota params.
Enable quota.
Disable quota.
View global quota parameters.
Set global quota parameters.
Enable a global quota.
Disable a global quota.
Create a new realm.
Remove a realm.
Show the realm info.
Get the default realm name.
List all realms.
List all realm periods.
Rename a realm.
Set the realm info (requires infile).
Set the realm as default.
Pull a realm and its current period.
Add a zone to a zonegroup.
Create a new zone group info.
Set the default zone group.
Remove a zone group info.
Show the zone group info.
Modify an existing zonegroup.
Set the zone group info (requires infile).
Remove a zone from a zonegroup.
Rename a zone group.
List all zone groups set on this cluster.
List zonegroup's placement targets.
Add a placement target id to a zonegroup.
Modify a placement target of a specific zonegroup.
Remove a placement target from a zonegroup.
Set a zonegroup's default placement target.
Create a new zone.
Remove a zone.
Show zone cluster params.
Set zone cluster params (requires infile).
Modify an existing zone.
List all zones set on this cluster.
Get metadata sync status.
Init metadata sync.
Run metadata sync.
Get data sync status of the specified source zone.
Init data sync for the specified source zone.
Run data sync for the specified source zone.
list sync error.
trim sync error.
Rename a zone.
List zone's placement targets.
Add a zone placement target.
Modify a zone placement target.
Remove a zone placement target.
Add an existing pool for data placement.
Remove an existing pool from data placement set.
List placement active set.
Display bucket/object policy.
List log objects.
Dump a log from specific object or (bucket + date + bucket-id). (NOTE: required to specify formatting of date to "YYYY-MM-DD-hh")
Remove log object.
Show the usage information (with optional user and date range).
Trim usage information (with optional user and date range).
Dump expired garbage collection objects (specify --include-all to list all entries, including unexpired).
Manually process garbage.
List all bucket lifecycle progress.
Manually process lifecycle.
Get metadata info.
Put metadata info.
Remove metadata info.
List metadata info.
List metadata log.
Trim metadata log.
Read metadata log status.
List bucket index log.
Trim bucket index log (use start-marker, end-marker).
List data log.
Trim data log.
Read data log status.
Init and run search for leaked rados objects. DEPRECATED. See the "rgw-orphan-list" tool.
Clean up search for leaked rados objects. DEPRECATED. See the "rgw-orphan-list" tool.
List the current job-ids for the orphans search. DEPRECATED. See the "rgw-orphan-list" tool.
create a new AWS role for use with STS.
Remove a role.
Get a role.
List the roles with specified path prefix.
Modify the assume role policy of an existing role.
Add/update permission policy to role.
List the policies attached to a role.
Get the specified inline policy document embedded with the given role.
Remove the policy attached to a role
Schedule a resharding of a bucket
List all bucket resharding or scheduled to be resharded
Process of scheduled reshard jobs
Resharding status of a bucket
Cancel resharding a bucket
topic list
List bucket notifications/pubsub topics
topic get
Get a bucket notifications/pubsub topic
topic rm
Remove a bucket notifications/pubsub topic
subscription get
Get a pubsub subscription definition
subscription rm
Remove a pubsub subscription
subscription pull
Show events in a pubsub subscription
subscription ack
Ack (remove) an events in a pubsub subscription


Use ceph.conf configuration file instead of the default /etc/ceph/ceph.conf to determine monitor addresses during startup.

Connect to specified monitor (instead of looking through ceph.conf).

Name of the tenant.

The radosgw user ID.

ID of the new user. Used with 'user rename' command.

Name of the subuser.

S3 access key.

The e-mail address of the user.

The secret key.

Generate random access key (for S3).

Generate random secret key.

key type, options are: swift, s3.

Temporary url key.

max number of buckets for a user (0 for no limit, negative value to disable bucket creation). Default is 1000.

Set the access permissions for the sub-user. Available access permissions are read, write, readwrite and full.

The display name of the user.

Set the admin flag on the user.

Set the system flag on the user.

Specify the bucket name. If tenant-id is not specified, the tenant-id of the user (--uid) is used.

Specify the pool name. Also used with orphans find as data pool to scan for leaked rados objects.

Specify the object name.

The date in the format yyyy-mm-dd.

The start date in the format yyyy-mm-dd.

The end date in the format yyyy-mm-dd.

Specify the bucket id.

While tenant-id/ can be specified, this is never necessary for normal operation.

Optional for mdlog list, bi list, data sync status. Required for mdlog trim.

Optional for listing operations to specify the max entires

When specified, user removal will also purge all the user data.

When specified, subuser removal will also purge all the subuser keys.

When specified, the bucket removal will also purge all objects in it.

Key to retrieve metadata from with metadata get.

Zone or zonegroup id of remote gateway.

Period id.

url for pushing/pulling period or realm.

Period epoch.

Commit the period during 'period update'.

Get the staging period info.

Set as master.

Master zone id.

The realm name.

The realm id.

New name of realm.

The zonegroup name.

The zonegroup id.

The new name of the zonegroup.

Zone in which radosgw is running.

The zone id.

The new name of the zone.

The source zone for data sync.

Set the entity (realm, zonegroup, zone) as default.

Set the zone as read-only when adding to the zonegroup.

Placement id for the zonegroup placement commands.

The list of tags for zonegroup placement add and modify commands.

The list of tags to add for zonegroup placement modify command.

The list of tags to remove for zonegroup placement modify command.

The zone endpoints.

The placement target index pool.

The placement target data pool.

The placement target data extra (non-ec) pool.

The placement target index type (normal, indexless, or #id).

The zone tier type.

Set zone tier config keys, values.

Unset zone tier config keys.

Set/reset whether zone syncs from all zonegroup peers.

Set the list of zones to sync from.

Remove the zones from list of zones to sync from.

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 applies to buckets that are created after the zone/zonegroup changes take effect.

Besides checking bucket index, will also fix it.

bucket check: Rebuilds bucket index according to actual objects state.

Specify output format for certain operations. Supported formats: xml, json.

Option for 'user stats' command. When specified, it will update user stats with the current stats reported by user's buckets indexes.

Enable/disable dump of log entries on log show.

Enable/disable dump of log summation on log show.

Log show only dumps entries that don't have zero value in one of the numeric field.

Specify a file to read in when setting data.

Comma separated list of categories, used in usage show.

List of caps (e.g., "usage=read, write; user=read".

Placement target compression algorithm (lz4|snappy|zlib|zstd)

Required for certain operations.

Specify the min object size for bucket rewrite (default 4M).

Specify the max object size for bucket rewrite (default ULLONG_MAX).

Specify the min stripe size for object rewrite (default 0). If the value is set to 0, then the specified object will always be rewritten for restriping.

When specified with bucket limit check, list only buckets nearing or over the current max objects per shard value.

When specified with bucket deletion, triggers object deletions by not involving GC.

When specified with bucket deletion and bypass-gc set to true, ignores bucket index consistency.

Maximum concurrent ios for bucket operations. 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. Default is 32.


Specify max objects (negative value to disable).

Specify max size (in B/K/M/G/T, negative value to disable).

The scope of quota (bucket, user).


Number of shards to use for keeping the temporary scan info

Number of seconds to wait before declaring an object to be an orphan. Default is 86400 (24 hours).

Set the job id (for orphans find)


Provide extra info in the job list.


The name of the role to create.

The path to the role.

The trust relationship policy document that grants an entity permission to assume the role.

The name of the policy document.

The permission policy document.

The path prefix for filtering the roles.


The bucket notifications/pubsub topic name.

The pubsub subscription name.

The event id in a pubsub subscription.


Generate a new user:

$ 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": []}

Remove a user:

$ radosgw-admin user rm --uid=johnny

Rename a user:

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

Remove a user and all associated buckets with their contents:

$ radosgw-admin user rm --uid=johnny --purge-data

Remove a bucket:

$ radosgw-admin bucket rm --bucket=foo

Link bucket to specified user:

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

Unlink bucket from specified user:

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

Rename a bucket:

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

Move a bucket from the old global tenant space to a specified tenant:

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

Link bucket to specified user and change object ACLs:

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

Show the logs of a bucket from April 1st, 2012:

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

Show usage information for user from March 1st to (but not including) April 1st, 2012:

$ radosgw-admin usage show --uid=johnny \

--start-date=2012-03-01 --end-date=2012-04-01

Show only summary of usage information for all users:

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

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

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


radosgw-admin is part of Ceph, a massively scalable, open-source, distributed storage system. Please refer to the Ceph documentation at for more information.


ceph(8) radosgw(8)


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

February 16, 2023 dev