Scroll to navigation

RADOSGW-ADMIN(8) Ceph RADOSGW-ADMIN(8)

NAME

radosgw-admin - rados REST gateway user administration utility

SYNOPSIS

radosgw-admin command [ options ... ]

DESCRIPTION

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

COMMANDS

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

Create a new user.
Modify a user.
Display information for a user including any 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 the 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 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.
Show bucket sharding stats.
Link bucket to specified user.
Unlink bucket from specified user.
Change bucket ownership to the specified user and update object ACLs. Invoke with --marker to resume if the command is 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 in the designated bucket, if --bucket=<bucket> is specified. Otherwise, list the RADOS objects that contain data for all buckets.
Reshard a bucket's index.
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 errors.
Trim sync errors.
Rename a zone.
List a 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 transitions. If a bucket is specified (e.g., via --bucket_id or via --bucket and optional --tenant), only that bucket is processed.
Get metadata info.
Put metadata info.
Remove metadata info.
List metadata info.
List metadata log which is needed for multi-site deployments.
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.
Read metadata log status.
List bucket index log which is needed for multi-site deployments.
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.
List data log which is needed for multi-site deployments.
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.
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 orphans search job IDs. DEPRECATED. See the "rgw-orphan-list" tool.
Create a new role for use with STS (Security Token Service).
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
Acknowledge (remove) events in a pubsub subscription

OPTIONS

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 selecting one from ceph.conf).

Name of the tenant.

The user on which to operate.

The new ID of the 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.

Maximum 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 subuser. 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.

Optional for bucket link; use to rename a bucket. While the tenant-id can be specified, this is not necessary in normal operation.

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

Optional for listing operations to specify the max entries.

When specified, user removal will also purge the user's data.

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

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

Key from which to retrieve metadata, used 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>
Master zone ID.

The realm name.

The realm ID.

New name for the realm.

The zonegroup name.

The zonegroup ID.

The new name of the zonegroup.

Zone in which the gateway 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).

Whether the placement target is configured to store a data chunk inline in head objects.

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 from which to sync.

Remove zone(s) from list of zones from which to sync.

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.

Fix the bucket index in addition to checking it.

Bucket check: Rebuilds the bucket index according to actual object state.

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

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

Show configuration.

Enable/disable dumping 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 when setting data.

Comma separated list of categories, used in usage show.

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

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

Required as a guardrail for certain destructive operations.

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

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

Specify the minimum stripe size for object rewrite (default 0). If the value is set to 0, then the specified object will always be rewritten when 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 deletion without involving GC.

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

Maximum concurrent 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. The default is 32.

QUOTA OPTIONS

Specify the maximum number of objects (negative value to disable).

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

The scope of quota (bucket, user).

ORPHANS SEARCH OPTIONS

Number of shards to use for temporary scan info

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

Set the job id (for orphans find)

ORPHANS LIST-JOBS OPTIONS

Provide extra info in the job list.

ROLE OPTIONS

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.

--path-prefix
The path prefix for filtering the roles.

BUCKET NOTIFICATIONS/PUBSUB OPTIONS

The bucket notifications/pubsub topic name.

The pubsub subscription name.

The event id in a pubsub subscription.

EXAMPLES

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=johnny --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


AVAILABILITY

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

SEE ALSO

ceph(8) radosgw(8)

COPYRIGHT

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

April 25, 2024 dev