1RADOSGW-ADMIN(8) Ceph RADOSGW-ADMIN(8)
2
6 radosgw-admin - rados REST gateway user administration utility
7
9 radosgw-admin command [ options ... ]
10
13 radosgw-admin is a Ceph Object Gateway user administration utility. It
14 is used to create and modify users.
15
17 radosgw-admin utility provides commands for administration purposes as
18 follows:
19 user create
21 Create a new user.
22 user modify
24 Modify a user.
25 user info
27 Display information for a user including any subusers and keys.
28 user rename
30 Renames a user.
31 user rm
33 Remove a user.
34 user suspend
36 Suspend a user.
37 user enable
39 Re-enable user after suspension.
40 user check
42 Check user info.
43 user stats
45 Show user stats as accounted by the quota subsystem.
46 user list
48 List all users.
49 caps add
51 Add user capabilities.
52 caps rm
54 Remove user capabilities.
55 subuser create
57 Create a new subuser (primarily useful for clients using the
58 Swift API).
59 subuser modify
61 Modify a subuser.
62 subuser rm
64 Remove a subuser.
65 key create
67 Create access key.
68 key rm Remove access key.
70 bucket list
72 List buckets, or, if a bucket is specified with
73 --bucket=<bucket>, list its objects. Adding --allow-unordered
74 removes the ordering requirement, possibly generating results
75 more quickly for buckets with large number of objects.
76 bucket limit check
78 Show bucket sharding stats.
79 bucket link
81 Link bucket to specified user.
82 bucket unlink
84 Unlink bucket from specified user.
85 bucket chown
87 Change bucket ownership to the specified user and update object
88 ACLs. Invoke with --marker to resume if the command is inter‐
89 rupted.
90 bucket stats
92 Returns bucket statistics.
93 bucket rm
95 Remove a bucket.
96 bucket check
98 Check bucket index.
99 bucket rewrite
101 Rewrite all objects in the specified bucket.
102 bucket radoslist
104 List the RADOS objects that contain the data for all objects in
105 the designated bucket, if --bucket=<bucket> is specified. Oth‐
106 erwise, list the RADOS objects that contain data for all buck‐
107 ets.
108 bucket reshard
110 Reshard a bucket's index.
111 bucket sync disable
113 Disable bucket sync.
114 bucket sync enable
116 Enable bucket sync.
117 bi get Retrieve bucket index object entries.
119 bi put Store bucket index object entries.
121 bi list
123 List raw bucket index entries.
124 bi purge
126 Purge bucket index entries.
127 object rm
129 Remove an object.
130 object stat
132 Stat an object for its metadata.
133 object unlink
135 Unlink object from bucket index.
136 object rewrite
138 Rewrite the specified object.
139 objects expire
141 Run expired objects cleanup.
142 period rm
144 Remove a period.
145 period get
147 Get the period info.
148 period get-current
150 Get the current period info.
151 period pull
153 Pull a period.
154 period push
156 Push a period.
157 period list
159 List all periods.
160 period update
162 Update the staging period.
163 period commit
165 Commit the staging period.
166 quota set
168 Set quota params.
169 quota enable
171 Enable quota.
172 quota disable
174 Disable quota.
175 global quota get
177 View global quota parameters.
178 global quota set
180 Set global quota parameters.
181 global quota enable
183 Enable a global quota.
184 global quota disable
186 Disable a global quota.
187 realm create
189 Create a new realm.
190 realm rm
192 Remove a realm.
193 realm get
195 Show the realm info.
196 realm get-default
198 Get the default realm name.
199 realm list
201 List all realms.
202 realm list-periods
204 List all realm periods.
205 realm rename
207 Rename a realm.
208 realm set
210 Set the realm info (requires infile).
211 realm default
213 Set the realm as default.
214 realm pull
216 Pull a realm and its current period.
217 zonegroup add
219 Add a zone to a zonegroup.
220 zonegroup create
222 Create a new zone group info.
223 zonegroup default
225 Set the default zone group.
226 zonegroup rm
228 Remove a zone group info.
229 zonegroup get
231 Show the zone group info.
232 zonegroup modify
234 Modify an existing zonegroup.
235 zonegroup set
237 Set the zone group info (requires infile).
238 zonegroup remove
240 Remove a zone from a zonegroup.
241 zonegroup rename
243 Rename a zone group.
244 zonegroup list
246 List all zone groups set on this cluster.
247 zonegroup placement list
249 List zonegroup's placement targets.
250 zonegroup placement add
252 Add a placement target id to a zonegroup.
253 zonegroup placement modify
255 Modify a placement target of a specific zonegroup.
256 zonegroup placement rm
258 Remove a placement target from a zonegroup.
259 zonegroup placement default
261 Set a zonegroup's default placement target.
262 zone create
264 Create a new zone.
265 zone rm
267 Remove a zone.
268 zone get
270 Show zone cluster params.
271 zone set
273 Set zone cluster params (requires infile).
274 zone modify
276 Modify an existing zone.
277 zone list
279 List all zones set on this cluster.
280 metadata sync status
282 Get metadata sync status.
283 metadata sync init
285 Init metadata sync.
286 metadata sync run
288 Run metadata sync.
289 data sync status
291 Get data sync status of the specified source zone.
292 data sync init
294 Init data sync for the specified source zone.
295 data sync run
297 Run data sync for the specified source zone.
298 sync error list
300 List sync errors.
301 sync error trim
303 Trim sync errors.
304 zone rename
306 Rename a zone.
307 zone placement list
309 List a zone's placement targets.
310 zone placement add
312 Add a zone placement target.
313 zone placement modify
315 Modify a zone placement target.
316 zone placement rm
318 Remove a zone placement target.
319 pool add
321 Add an existing pool for data placement.
322 pool rm
324 Remove an existing pool from data placement set.
325 pools list
327 List placement active set.
328 policy Display bucket/object policy.
330 log list
332 List log objects.
333 log show
335 Dump a log from specific object or (bucket + date + bucket-id).
336 (NOTE: required to specify formatting of date to
337 "YYYY-MM-DD-hh")
338 log rm Remove log object.
340 usage show
342 Show the usage information (with optional user and date range).
343 usage trim
345 Trim usage information (with optional user and date range).
346 gc list
348 Dump expired garbage collection objects (specify --include-all
349 to list all entries, including unexpired).
350 gc process
352 Manually process garbage.
353 lc list
355 List all bucket lifecycle progress.
356 lc process
358 Manually process lifecycle transitions. If a bucket is speci‐
359 fied (e.g., via --bucket_id or via --bucket and optional --ten‐
360 ant), only that bucket is processed.
361 metadata get
363 Get metadata info.
364 metadata put
366 Put metadata info.
367 metadata rm
369 Remove metadata info.
370 metadata list
372 List metadata info.
373 mdlog list
375 List metadata log which is needed for multi-site deployments.
376 mdlog trim
378 Trim metadata log manually instead of relying on the gateway's
379 integrated log sync. Before trimming, compare the listings and
380 make sure the last sync was complete, otherwise it can reiniti‐
381 ate a sync.
382 mdlog status
384 Read metadata log status.
385 bilog list
387 List bucket index log which is needed for multi-site deploy‐
388 ments.
389 bilog trim
391 Trim bucket index log (use start-marker, end-marker) manually
392 instead of relying on the gateway's integrated log sync. Before
393 trimming, compare the listings and make sure the last sync was
394 complete, otherwise it can reinitiate a sync.
395 datalog list
397 List data log which is needed for multi-site deployments.
398 datalog trim
400 Trim data log manually instead of relying on the gateway's inte‐
401 grated log sync. Before trimming, compare the listings and make
402 sure the last sync was complete, otherwise it can reinitiate a
403 sync.
404 datalog status
406 Read data log status.
407 orphans find
409 Init and run search for leaked RADOS objects. DEPRECATED. See
410 the "rgw-orphan-list" tool.
411 orphans finish
413 Clean up search for leaked RADOS objects. DEPRECATED. See the
414 "rgw-orphan-list" tool.
415 orphans list-jobs
417 List the current orphans search job IDs. DEPRECATED. See the
418 "rgw-orphan-list" tool.
419 role create
421 Create a new role for use with STS (Security Token Service).
422 role rm
424 Remove a role.
425 role get
427 Get a role.
428 role list
430 List the roles with specified path prefix.
431 role modify
433 Modify the assume role policy of an existing role.
434 role-policy put
436 Add/update permission policy to role.
437 role-policy list
439 List the policies attached to a role.
440 role-policy get
442 Get the specified inline policy document embedded with the given
443 role.
444 role-policy rm
446 Remove the policy attached to a role
447 reshard add
449 Schedule a resharding of a bucket
450 reshard list
452 List all bucket resharding or scheduled to be resharded
453 reshard process
455 Process of scheduled reshard jobs
456 reshard status
458 Resharding status of a bucket
459 reshard cancel
461 Cancel resharding a bucket
462 topic list
464 List bucket notifications/pubsub topics
465 topic get
467 Get a bucket notifications/pubsub topic
468 topic rm
470 Remove a bucket notifications/pubsub topic
471 subscription get
473 Get a pubsub subscription definition
474 subscription rm
476 Remove a pubsub subscription
477 subscription pull
479 Show events in a pubsub subscription
480 subscription ack
482 Acknowledge (remove) events in a pubsub subscription
483
485 -c ceph.conf, --conf=ceph.conf
486 Use ceph.conf configuration file instead of the default
487 /etc/ceph/ceph.conf to determine monitor addresses during
488 startup.
489 -m monaddress[:port]
491 Connect to specified monitor (instead of selecting one from
492 ceph.conf).
493 --tenant=<tenant>
495 Name of the tenant.
496 --uid=uid
498 The user on which to operate.
499 --new-uid=uid
501 The new ID of the user. Used with 'user rename' command.
502 --subuser=<name>
504 Name of the subuser.
505 --access-key=<key>
507 S3 access key.
508 --email=email
510 The e-mail address of the user.
511 --secret/--secret-key=<key>
513 The secret key.
514 --gen-access-key
516 Generate random access key (for S3).
517 --gen-secret
519 Generate random secret key.
520 --key-type=<type>
522 Key type, options are: swift, s3.
523 --temp-url-key[-2]=<key>
525 Temporary URL key.
526 --max-buckets
528 Maximum number of buckets for a user (0 for no limit, negative
529 value to disable bucket creation). Default is 1000.
530 --access=<access>
532 Set the access permissions for the subuser. Available access
533 permissions are read, write, readwrite and full.
534 --display-name=<name>
536 The display name of the user.
537 --admin
539 Set the admin flag on the user.
540 --system
542 Set the system flag on the user.
543 --bucket=[tenant-id/]bucket
545 Specify the bucket name. If tenant-id is not specified, the
546 tenant-id of the user (--uid) is used.
547 --pool=<pool>
549 Specify the pool name. Also used with orphans find as data pool
550 to scan for leaked rados objects.
551 --object=object
553 Specify the object name.
554 --date=yyyy-mm-dd
556 The date in the format yyyy-mm-dd.
557 --start-date=yyyy-mm-dd
559 The start date in the format yyyy-mm-dd.
560 --end-date=yyyy-mm-dd
562 The end date in the format yyyy-mm-dd.
563 --bucket-id=<bucket-id>
565 Specify the bucket id.
566 --bucket-new-name=[tenant-id/]<bucket>
568 Optional for bucket link; use to rename a bucket. While the
569 tenant-id can be specified, this is not necessary in normal op‐
570 eration.
571 --shard-id=<shard-id>
573 Optional for mdlog list, bi list, data sync status. Required for
574 mdlog trim.
575 --max-entries=<entries>
577 Optional for listing operations to specify the max entries.
578 --purge-data
580 When specified, user removal will also purge the user's data.
581 --purge-keys
583 When specified, subuser removal will also purge the subuser'
584 keys.
585 --purge-objects
587 When specified, the bucket removal will also purge all objects
588 in it.
589 --metadata-key=<key>
591 Key from which to retrieve metadata, used with metadata get.
592 --remote=<remote>
594 Zone or zonegroup id of remote gateway.
595 --period=<id>
597 Period ID.
598 --url=<url>
600 URL for pushing/pulling period or realm.
601 --epoch=<number>
603 Period epoch.
604 --commit
606 Commit the period during 'period update'.
607 --staging
609 Get the staging period info.
610 --master
612 Set as master.
613 --master-zone=<id>
615 Master zone ID.
616 --rgw-realm=<name>
618 The realm name.
619 --realm-id=<id>
621 The realm ID.
622 --realm-new-name=<name>
624 New name for the realm.
625 --rgw-zonegroup=<name>
627 The zonegroup name.
628 --zonegroup-id=<id>
630 The zonegroup ID.
631 --zonegroup-new-name=<name>
633 The new name of the zonegroup.
634 --rgw-zone=<zone>
636 Zone in which the gateway is running.
637 --zone-id=<id>
639 The zone ID.
640 --zone-new-name=<name>
642 The new name of the zone.
643 --source-zone
645 The source zone for data sync.
646 --default
648 Set the entity (realm, zonegroup, zone) as default.
649 --read-only
651 Set the zone as read-only when adding to the zonegroup.
652 --placement-id
654 Placement ID for the zonegroup placement commands.
655 --tags=<list>
657 The list of tags for zonegroup placement add and modify com‐
658 mands.
659 --tags-add=<list>
661 The list of tags to add for zonegroup placement modify command.
662 --tags-rm=<list>
664 The list of tags to remove for zonegroup placement modify com‐
665 mand.
666 --endpoints=<list>
668 The zone endpoints.
669 --index-pool=<pool>
671 The placement target index pool.
672 --data-pool=<pool>
674 The placement target data pool.
675 --data-extra-pool=<pool>
677 The placement target data extra (non-EC) pool.
678 --placement-index-type=<type>
680 The placement target index type (normal, indexless, or #id).
681 --placement-inline-data=<true>
683 Whether the placement target is configured to store a data chunk
684 inline in head objects.
685 --tier-type=<type>
687 The zone tier type.
688 --tier-config=<k>=<v>[,...]
690 Set zone tier config keys, values.
691 --tier-config-rm=<k>[,...]
693 Unset zone tier config keys.
694 --sync-from-all[=false]
696 Set/reset whether zone syncs from all zonegroup peers.
697 --sync-from=[zone-name][,...]
699 Set the list of zones from which to sync.
700 --sync-from-rm=[zone-name][,...]
702 Remove zone(s) from list of zones from which to sync.
703 --bucket-index-max-shards
705 Override a zone's or zonegroup's default number of bucket index
706 shards. This option is accepted by the 'zone create', 'zone mod‐
707 ify', 'zonegroup add', and 'zonegroup modify' commands, and ap‐
708 plies to buckets that are created after the zone/zonegroup
709 changes take effect.
710 --fix Fix the bucket index in addition to checking it.
712 --check-objects
714 Bucket check: Rebuilds the bucket index according to actual ob‐
715 ject state.
716 --format=<format>
718 Specify output format for certain operations. Supported formats:
719 xml, json.
720 --sync-stats
722 Option for the 'user stats' command. When specified, it will up‐
723 date user stats with the current stats reported by the user's
724 buckets indexes.
725 --show-config
727 Show configuration.
728 --show-log-entries=<flag>
730 Enable/disable dumping of log entries on log show.
731 --show-log-sum=<flag>
733 Enable/disable dump of log summation on log show.
734 --skip-zero-entries
736 Log show only dumps entries that don't have zero value in one of
737 the numeric field.
738 --infile
740 Specify a file to read when setting data.
741 --categories=<list>
743 Comma separated list of categories, used in usage show.
744 --caps=<caps>
746 List of capabilities (e.g., "usage=read, write; user=read").
747 --compression=<compression-algorithm>
749 Placement target compression algorithm (lz4|snappy|zlib|zstd).
750 --yes-i-really-mean-it
752 Required as a guardrail for certain destructive operations.
753 --min-rewrite-size
755 Specify the minimum object size for bucket rewrite (default 4M).
756 --max-rewrite-size
758 Specify the maximum object size for bucket rewrite (default UL‐
759 LONG_MAX).
760 --min-rewrite-stripe-size
762 Specify the minimum stripe size for object rewrite (default 0).
763 If the value is set to 0, then the specified object will always
764 be rewritten when restriping.
765 --warnings-only
767 When specified with bucket limit check, list only buckets near‐
768 ing or over the current max objects per shard value.
769 --bypass-gc
771 When specified with bucket deletion, triggers object deletion
772 without involving GC.
773 --inconsistent-index
775 When specified with bucket deletion and bypass-gc set to true,
776 ignores bucket index consistency.
777 --max-concurrent-ios
779 Maximum concurrent bucket operations. Affects operations that
780 scan the bucket index, e.g., listing, deletion, and all
781 scan/search operations such as finding orphans or checking the
782 bucket index. The default is 32.
783
785 --max-objects
786 Specify the maximum number of objects (negative value to dis‐
787 able).
788 --max-size
790 Specify the maximum object size (in B/K/M/G/T, negative value to
791 disable).
792 --quota-scope
794 The scope of quota (bucket, user).
795
797 --num-shards
798 Number of shards to use for temporary scan info
799 --orphan-stale-secs
801 Number of seconds to wait before declaring an object to be an
802 orphan. The efault is 86400 (24 hours).
803 --job-id
805 Set the job id (for orphans find)
806
808 --extra-info
809 Provide extra info in the job list.
810
812 --role-name
813 The name of the role to create.
814 --path The path to the role.
816 --assume-role-policy-doc
818 The trust relationship policy document that grants an entity
819 permission to assume the role.
820 --policy-name
822 The name of the policy document.
823 --policy-doc
825 The permission policy document.
826 --path-prefix
828 The path prefix for filtering the roles.
829
831 --topic
832 The bucket notifications/pubsub topic name.
833 --subscription
835 The pubsub subscription name.
836 --event-id
838 The event id in a pubsub subscription.
839
841 Generate a new user:
842 $ radosgw-admin user create --display-name="johnny rotten" --uid=johnny
844 { "user_id": "johnny",
845 "rados_uid": 0,
846 "display_name": "johnny rotten",
847 "email": "",
848 "suspended": 0,
849 "subusers": [],
850 "keys": [
851 { "user": "johnny",
852 "access_key": "TCICW53D9BQ2VGC46I44",
853 "secret_key": "tfm9aHMI8X76L3UdgE+ZQaJag1vJQmE6HDb5Lbrz"}],
854 "swift_keys": []}
855 Remove a user:
857 $ radosgw-admin user rm --uid=johnny
859 Rename a user:
861 $ radosgw-admin user rename --uid=johny --new-uid=joe
863 Remove a user and all associated buckets with their contents:
865 $ radosgw-admin user rm --uid=johnny --purge-data
867 Remove a bucket:
869 $ radosgw-admin bucket rm --bucket=foo
871 Link bucket to specified user:
873 $ radosgw-admin bucket link --bucket=foo --bucket_id=<bucket id> --uid=johnny
875 Unlink bucket from specified user:
877 $ radosgw-admin bucket unlink --bucket=foo --uid=johnny
879 Rename a bucket:
881 $ radosgw-admin bucket link --bucket=foo --bucket-new-name=bar --uid=johnny
883 Move a bucket from the old global tenant space to a specified tenant:
885 $ radosgw-admin bucket link --bucket=/foo --uid=12345678$12345678'
887 Link bucket to specified user and change object ACLs:
889 $ radosgw-admin bucket chown --bucket=/foo --uid=12345678$12345678'
891 Show the logs of a bucket from April 1st, 2012:
893 $ radosgw-admin log show --bucket=foo --date=2012-04-01-01 --bucket-id=default.14193.1
895 Show usage information for user from March 1st to (but not including)
897 April 1st, 2012:
898 $ radosgw-admin usage show --uid=johnny \
900 --start-date=2012-03-01 --end-date=2012-04-01
901 Show only summary of usage information for all users:
903 $ radosgw-admin usage show --show-log-entries=false
905 Trim usage information for user until March 1st, 2012:
907 $ radosgw-admin usage trim --uid=johnny --end-date=2012-04-01
909
911 radosgw-admin is part of Ceph, a massively scalable, open-source, dis‐
912 tributed storage system. Please refer to the Ceph documentation at
913 https://docs.ceph.com for more information.
914
916 ceph(8) radosgw(8)
917
919 2010-2023, Inktank Storage, Inc. and contributors. Licensed under Cre‐
920 ative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0)
921dev Nov 02, 2023 RADOSGW-ADMIN(8)