1RADOSGW-ADMIN(8)                     Ceph                     RADOSGW-ADMIN(8)
2
3
4

NAME

6       radosgw-admin - rados REST gateway user administration utility
7

SYNOPSIS

9       radosgw-admin command [ options ... ]
10
11

DESCRIPTION

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

COMMANDS

17       radosgw-admin utility uses many  commands  for  administration  purpose
18       which are as follows:
19
20       user create
21              Create a new user.
22
23       user modify
24              Modify a user.
25
26       user info
27              Display  information  of  a  user, and any potentially available
28              subusers and keys.
29
30       user rename
31              Renames a user.
32
33       user rm
34              Remove a user.
35
36       user suspend
37              Suspend a user.
38
39       user enable
40              Re-enable user after suspension.
41
42       user check
43              Check user info.
44
45       user stats
46              Show user stats as accounted by quota subsystem.
47
48       user list
49              List all users.
50
51       caps add
52              Add user capabilities.
53
54       caps rm
55              Remove user capabilities.
56
57       subuser create
58              Create a new subuser (primarily useful  for  clients  using  the
59              Swift API).
60
61       subuser modify
62              Modify a subuser.
63
64       subuser rm
65              Remove a subuser.
66
67       key create
68              Create access key.
69
70       key rm Remove access key.
71
72       bucket list
73              List  buckets,  or,  if bucket specified with --bucket=<bucket>,
74              list its objects. If bucket specified  adding  --allow-unordered
75              removes  ordering  requirement, possibly generating results more
76              quickly in buckets with large number of objects.
77
78       bucket limit check
79              Show bucket sharding stats.
80
81       bucket link
82              Link bucket to specified user.
83
84       bucket unlink
85              Unlink bucket from specified user.
86
87       bucket chown
88              Link bucket to specified  user  and  update  object  ACLs.   Use
89              --marker to resume if command gets interrupted.
90
91       bucket stats
92              Returns bucket statistics.
93
94       bucket rm
95              Remove a bucket.
96
97       bucket check
98              Check bucket index.
99
100       bucket rewrite
101              Rewrite all objects in the specified bucket.
102
103       bucket radoslist
104              List  the rados objects that contain the data for all objects is
105              the designated bucket, if  --bucket=<bucket>  is  specified,  or
106              otherwise all buckets.
107
108       bucket reshard
109              Reshard a bucket.
110
111       bucket sync disable
112              Disable bucket sync.
113
114       bucket sync enable
115              Enable bucket sync.
116
117       bi get Retrieve bucket index object entries.
118
119       bi put Store bucket index object entries.
120
121       bi list
122              List raw bucket index entries.
123
124       bi purge
125              Purge bucket index entries.
126
127       object rm
128              Remove an object.
129
130       object stat
131              Stat an object for its metadata.
132
133       object unlink
134              Unlink object from bucket index.
135
136       object rewrite
137              Rewrite the specified object.
138
139       objects expire
140              Run expired objects cleanup.
141
142       period rm
143              Remove a period.
144
145       period get
146              Get the period info.
147
148       period get-current
149              Get the current period info.
150
151       period pull
152              Pull a period.
153
154       period push
155              Push a period.
156
157       period list
158              List all periods.
159
160       period update
161              Update the staging period.
162
163       period commit
164              Commit the staging period.
165
166       quota set
167              Set quota params.
168
169       quota enable
170              Enable quota.
171
172       quota disable
173              Disable quota.
174
175       global quota get
176              View global quota parameters.
177
178       global quota set
179              Set global quota parameters.
180
181       global quota enable
182              Enable a global quota.
183
184       global quota disable
185              Disable a global quota.
186
187       realm create
188              Create a new realm.
189
190       realm rm
191              Remove a realm.
192
193       realm get
194              Show the realm info.
195
196       realm get-default
197              Get the default realm name.
198
199       realm list
200              List all realms.
201
202       realm list-periods
203              List all realm periods.
204
205       realm rename
206              Rename a realm.
207
208       realm set
209              Set the realm info (requires infile).
210
211       realm default
212              Set the realm as default.
213
214       realm pull
215              Pull a realm and its current period.
216
217       zonegroup add
218              Add a zone to a zonegroup.
219
220       zonegroup create
221              Create a new zone group info.
222
223       zonegroup default
224              Set the default zone group.
225
226       zonegroup rm
227              Remove a zone group info.
228
229       zonegroup get
230              Show the zone group info.
231
232       zonegroup modify
233              Modify an existing zonegroup.
234
235       zonegroup set
236              Set the zone group info (requires infile).
237
238       zonegroup remove
239              Remove a zone from a zonegroup.
240
241       zonegroup rename
242              Rename a zone group.
243
244       zonegroup list
245              List all zone groups set on this cluster.
246
247       zonegroup placement list
248              List zonegroup's placement targets.
249
250       zonegroup placement add
251              Add a placement target id to a zonegroup.
252
253       zonegroup placement modify
254              Modify a placement target of a specific zonegroup.
255
256       zonegroup placement rm
257              Remove a placement target from a zonegroup.
258
259       zonegroup placement default
260              Set a zonegroup's default placement target.
261
262       zone create
263              Create a new zone.
264
265       zone rm
266              Remove a zone.
267
268       zone get
269              Show zone cluster params.
270
271       zone set
272              Set zone cluster params (requires infile).
273
274       zone modify
275              Modify an existing zone.
276
277       zone list
278              List all zones set on this cluster.
279
280       metadata sync status
281              Get metadata sync status.
282
283       metadata sync init
284              Init metadata sync.
285
286       metadata sync run
287              Run metadata sync.
288
289       data sync status
290              Get data sync status of the specified source zone.
291
292       data sync init
293              Init data sync for the specified source zone.
294
295       data sync run
296              Run data sync for the specified source zone.
297
298       sync error list
299              list sync error.
300
301       sync error trim
302              trim sync error.
303
304       zone rename
305              Rename a zone.
306
307       zone placement list
308              List zone's placement targets.
309
310       zone placement add
311              Add a zone placement target.
312
313       zone placement modify
314              Modify a zone placement target.
315
316       zone placement rm
317              Remove a zone placement target.
318
319       pool add
320              Add an existing pool for data placement.
321
322       pool rm
323              Remove an existing pool from data placement set.
324
325       pools list
326              List placement active set.
327
328       policy Display bucket/object policy.
329
330       log list
331              List log objects.
332
333       log show
334              Dump  a log from specific object or (bucket + date + bucket-id).
335              (NOTE:   required   to   specify   formatting   of    date    to
336              "YYYY-MM-DD-hh")
337
338       log rm Remove log object.
339
340       usage show
341              Show the usage information (with optional user and date range).
342
343       usage trim
344              Trim usage information (with optional user and date range).
345
346       gc list
347              Dump  expired  garbage collection objects (specify --include-all
348              to list all entries, including unexpired).
349
350       gc process
351              Manually process garbage.
352
353       lc list
354              List all bucket lifecycle progress.
355
356       lc process
357              Manually process lifecycle.
358
359       metadata get
360              Get metadata info.
361
362       metadata put
363              Put metadata info.
364
365       metadata rm
366              Remove metadata info.
367
368       metadata list
369              List metadata info.
370
371       mdlog list
372              List metadata log.
373
374       mdlog trim
375              Trim metadata log.
376
377       mdlog status
378              Read metadata log status.
379
380       bilog list
381              List bucket index log.
382
383       bilog trim
384              Trim bucket index log (use start-marker, end-marker).
385
386       datalog list
387              List data log.
388
389       datalog trim
390              Trim data log.
391
392       datalog status
393              Read data log status.
394
395       orphans find
396              Init and run search for leaked rados objects.   DEPRECATED.  See
397              the "rgw-orphan-list" tool.
398
399       orphans finish
400              Clean  up  search for leaked rados objects.  DEPRECATED. See the
401              "rgw-orphan-list" tool.
402
403       orphans list-jobs
404              List the current job-ids for the  orphans  search.   DEPRECATED.
405              See the "rgw-orphan-list" tool.
406
407       role create
408              create a new AWS role for use with STS.
409
410       role rm
411              Remove a role.
412
413       role get
414              Get a role.
415
416       role list
417              List the roles with specified path prefix.
418
419       role modify
420              Modify the assume role policy of an existing role.
421
422       role-policy put
423              Add/update permission policy to role.
424
425       role-policy list
426              List the policies attached to a role.
427
428       role-policy get
429              Get the specified inline policy document embedded with the given
430              role.
431
432       role-policy rm
433              Remove the policy attached to a role
434
435       reshard add
436              Schedule a resharding of a bucket
437
438       reshard list
439              List all bucket resharding or scheduled to be resharded
440
441       reshard process
442              Process of scheduled reshard jobs
443
444       reshard status
445              Resharding status of a bucket
446
447       reshard cancel
448              Cancel resharding a bucket
449
450       topic list
451              List bucket notifications/pubsub topics
452
453       topic get
454              Get a bucket notifications/pubsub topic
455
456       topic rm
457              Remove a bucket notifications/pubsub topic
458
459       subscription get
460              Get a pubsub subscription definition
461
462       subscription rm
463              Remove a pubsub subscription
464
465       subscription pull
466              Show events in a pubsub subscription
467
468       subscription ack
469              Ack (remove) an events in a pubsub subscription
470

OPTIONS

472       -c ceph.conf, --conf=ceph.conf
473              Use  ceph.conf  configuration  file  instead  of   the   default
474              /etc/ceph/ceph.conf   to   determine  monitor  addresses  during
475              startup.
476
477       -m monaddress[:port]
478              Connect  to  specified  monitor  (instead  of  looking   through
479              ceph.conf).
480
481       --tenant=<tenant>
482              Name of the tenant.
483
484       --uid=uid
485              The radosgw user ID.
486
487       --new-uid=uid
488              ID of the new user. Used with 'user rename' command.
489
490       --subuser=<name>
491              Name of the subuser.
492
493       --access-key=<key>
494              S3 access key.
495
496       --email=email
497              The e-mail address of the user.
498
499       --secret/--secret-key=<key>
500              The secret key.
501
502       --gen-access-key
503              Generate random access key (for S3).
504
505       --gen-secret
506              Generate random secret key.
507
508       --key-type=<type>
509              key type, options are: swift, s3.
510
511       --temp-url-key[-2]=<key>
512              Temporary url key.
513
514       --max-buckets
515              max number of buckets for a user (0 for no limit, negative value
516              to disable bucket creation).  Default is 1000.
517
518       --access=<access>
519              Set the access permissions for the sub-user.   Available  access
520              permissions are read, write, readwrite and full.
521
522       --display-name=<name>
523              The display name of the user.
524
525       --admin
526              Set the admin flag on the user.
527
528       --system
529              Set the system flag on the user.
530
531       --bucket=[tenant-id/]bucket
532              Specify  the  bucket  name.   If tenant-id is not specified, the
533              tenant-id of the user (--uid) is used.
534
535       --pool=<pool>
536              Specify the pool name.  Also used with orphans find as data pool
537              to scan for leaked rados objects.
538
539       --object=object
540              Specify the object name.
541
542       --date=yyyy-mm-dd
543              The date in the format yyyy-mm-dd.
544
545       --start-date=yyyy-mm-dd
546              The start date in the format yyyy-mm-dd.
547
548       --end-date=yyyy-mm-dd
549              The end date in the format yyyy-mm-dd.
550
551       --bucket-id=<bucket-id>
552              Specify the bucket id.
553
554       --bucket-new-name=[tenant-id/]<bucket>
555
556              Optional for bucket link; use to rename a bucket.
557                     While  tenant-id/  can be specified, this is never neces‐
558                     sary for normal operation.
559
560       --shard-id=<shard-id>
561              Optional for mdlog list, bi list, data sync status. Required for
562              mdlog trim.
563
564       --max-entries=<entries>
565              Optional for listing operations to specify the max entires
566
567       --purge-data
568              When specified, user removal will also purge all the user data.
569
570       --purge-keys
571              When  specified, subuser removal will also purge all the subuser
572              keys.
573
574       --purge-objects
575              When specified, the bucket removal will also purge  all  objects
576              in it.
577
578       --metadata-key=<key>
579              Key to retrieve metadata from with metadata get.
580
581       --remote=<remote>
582              Zone or zonegroup id of remote gateway.
583
584       --period=<id>
585              Period id.
586
587       --url=<url>
588              url for pushing/pulling period or realm.
589
590       --epoch=<number>
591              Period epoch.
592
593       --commit
594              Commit the period during 'period update'.
595
596       --staging
597              Get the staging period info.
598
599       --master
600              Set as master.
601
602       --master-zone=<id>
603              Master zone id.
604
605       --rgw-realm=<name>
606              The realm name.
607
608       --realm-id=<id>
609              The realm id.
610
611       --realm-new-name=<name>
612              New name of realm.
613
614       --rgw-zonegroup=<name>
615              The zonegroup name.
616
617       --zonegroup-id=<id>
618              The zonegroup id.
619
620       --zonegroup-new-name=<name>
621              The new name of the zonegroup.
622
623       --rgw-zone=<zone>
624              Zone in which radosgw is running.
625
626       --zone-id=<id>
627              The zone id.
628
629       --zone-new-name=<name>
630              The new name of the zone.
631
632       --source-zone
633              The source zone for data sync.
634
635       --default
636              Set the entity (realm, zonegroup, zone) as default.
637
638       --read-only
639              Set the zone as read-only when adding to the zonegroup.
640
641       --placement-id
642              Placement id for the zonegroup placement commands.
643
644       --tags=<list>
645              The  list  of  tags  for zonegroup placement add and modify com‐
646              mands.
647
648       --tags-add=<list>
649              The list of tags to add for zonegroup placement modify command.
650
651       --tags-rm=<list>
652              The list of tags to remove for zonegroup placement  modify  com‐
653              mand.
654
655       --endpoints=<list>
656              The zone endpoints.
657
658       --index-pool=<pool>
659              The placement target index pool.
660
661       --data-pool=<pool>
662              The placement target data pool.
663
664       --data-extra-pool=<pool>
665              The placement target data extra (non-ec) pool.
666
667       --placement-index-type=<type>
668              The placement target index type (normal, indexless, or #id).
669
670       --tier-type=<type>
671              The zone tier type.
672
673       --tier-config=<k>=<v>[,...]
674              Set zone tier config keys, values.
675
676       --tier-config-rm=<k>[,...]
677              Unset zone tier config keys.
678
679       --sync-from-all[=false]
680              Set/reset whether zone syncs from all zonegroup peers.
681
682       --sync-from=[zone-name][,...]
683              Set the list of zones to sync from.
684
685       --sync-from-rm=[zone-name][,...]
686              Remove the zones from list of zones to sync from.
687
688       --bucket-index-max-shards
689              Override  a zone's or zonegroup's default number of bucket index
690              shards. This option is accepted by the 'zone create', 'zone mod‐
691              ify',  'zonegroup add', and 'zonegroup modify' commands, and ap‐
692              plies to buckets  that  are  created  after  the  zone/zonegroup
693              changes take effect.
694
695       --fix  Besides checking bucket index, will also fix it.
696
697       --check-objects
698              bucket  check: Rebuilds bucket index according to actual objects
699              state.
700
701       --format=<format>
702              Specify output format for certain operations. Supported formats:
703              xml, json.
704
705       --sync-stats
706              Option  for 'user stats' command. When specified, it will update
707              user stats with the current stats reported by user's buckets in‐
708              dexes.
709
710       --show-log-entries=<flag>
711              Enable/disable dump of log entries on log show.
712
713       --show-log-sum=<flag>
714              Enable/disable dump of log summation on log show.
715
716       --skip-zero-entries
717              Log show only dumps entries that don't have zero value in one of
718              the numeric field.
719
720       --infile
721              Specify a file to read in when setting data.
722
723       --categories=<list>
724              Comma separated list of categories, used in usage show.
725
726       --caps=<caps>
727              List of caps (e.g., "usage=read, write; user=read".
728
729       --compression=<compression-algorithm>
730              Placement target compression algorithm (lz4|snappy|zlib|zstd)
731
732       --yes-i-really-mean-it
733              Required for certain operations.
734
735       --min-rewrite-size
736              Specify the min object size for bucket rewrite (default 4M).
737
738       --max-rewrite-size
739              Specify the max object size  for  bucket  rewrite  (default  UL‐
740              LONG_MAX).
741
742       --min-rewrite-stripe-size
743              Specify  the  min stripe size for object rewrite (default 0). If
744              the value is set to 0, then the specified object will always  be
745              rewritten for restriping.
746
747       --warnings-only
748              When  specified with bucket limit check, list only buckets near‐
749              ing or over the current max objects per shard value.
750
751       --bypass-gc
752              When specified with bucket deletion, triggers  object  deletions
753              by not involving GC.
754
755       --inconsistent-index
756              When  specified  with bucket deletion and bypass-gc set to true,
757              ignores bucket index consistency.
758
759       --max-concurrent-ios
760              Maximum concurrent ios for bucket operations. Affects operations
761              that  scan  the  bucket  index, e.g., listing, deletion, and all
762              scan/search operations such as finding orphans or  checking  the
763              bucket index.  Default is 32.
764

QUOTA OPTIONS

766       --max-objects
767              Specify max objects (negative value to disable).
768
769       --max-size
770              Specify max size (in B/K/M/G/T, negative value to disable).
771
772       --quota-scope
773              The scope of quota (bucket, user).
774

ORPHANS SEARCH OPTIONS

776       --num-shards
777              Number of shards to use for keeping the temporary scan info
778
779       --orphan-stale-secs
780              Number  of  seconds  to wait before declaring an object to be an
781              orphan.  Default is 86400 (24 hours).
782
783       --job-id
784              Set the job id (for orphans find)
785

ORPHANS LIST-JOBS OPTIONS

787       --extra-info
788              Provide extra info in the job list.
789

ROLE OPTIONS

791       --role-name
792              The name of the role to create.
793
794       --path The path to the role.
795
796       --assume-role-policy-doc
797              The trust relationship policy document  that  grants  an  entity
798              permission to assume the role.
799
800       --policy-name
801              The name of the policy document.
802
803       --policy-doc
804              The permission policy document.
805
806       --path-prefix
807              The path prefix for filtering the roles.
808

BUCKET NOTIFICATIONS/PUBSUB OPTIONS

810       --topic
811              The bucket notifications/pubsub topic name.
812
813       --subscription
814              The pubsub subscription name.
815
816       --event-id
817              The event id in a pubsub subscription.
818

EXAMPLES

820       Generate a new user:
821
822          $ radosgw-admin user create --display-name="johnny rotten" --uid=johnny
823          { "user_id": "johnny",
824            "rados_uid": 0,
825            "display_name": "johnny rotten",
826            "email": "",
827            "suspended": 0,
828            "subusers": [],
829            "keys": [
830                  { "user": "johnny",
831                    "access_key": "TCICW53D9BQ2VGC46I44",
832                    "secret_key": "tfm9aHMI8X76L3UdgE+ZQaJag1vJQmE6HDb5Lbrz"}],
833            "swift_keys": []}
834
835       Remove a user:
836
837          $ radosgw-admin user rm --uid=johnny
838
839       Rename a user:
840
841          $ radosgw-admin user rename --uid=johny --new-uid=joe
842
843       Remove a user and all associated buckets with their contents:
844
845          $ radosgw-admin user rm --uid=johnny --purge-data
846
847       Remove a bucket:
848
849          $ radosgw-admin bucket rm --bucket=foo
850
851       Link bucket to specified user:
852
853          $ radosgw-admin bucket link --bucket=foo --bucket_id=<bucket id> --uid=johnny
854
855       Unlink bucket from specified user:
856
857          $ radosgw-admin bucket unlink --bucket=foo --uid=johnny
858
859       Rename a bucket:
860
861          $ radosgw-admin bucket link --bucket=foo --bucket-new-name=bar --uid=johnny
862
863       Move a bucket from the old global tenant space to a specified tenant:
864
865          $ radosgw-admin bucket link --bucket=/foo --uid=12345678$12345678'
866
867       Link bucket to specified user and change object ACLs:
868
869          $ radosgw-admin bucket chown --bucket=/foo --uid=12345678$12345678'
870
871       Show the logs of a bucket from April 1st, 2012:
872
873          $ radosgw-admin log show --bucket=foo --date=2012-04-01-01 --bucket-id=default.14193.1
874
875       Show  usage  information for user from March 1st to (but not including)
876       April 1st, 2012:
877
878          $ radosgw-admin usage show --uid=johnny \
879                          --start-date=2012-03-01 --end-date=2012-04-01
880
881       Show only summary of usage information for all users:
882
883          $ radosgw-admin usage show --show-log-entries=false
884
885       Trim usage information for user until March 1st, 2012:
886
887          $ radosgw-admin usage trim --uid=johnny --end-date=2012-04-01
888

AVAILABILITY

890       radosgw-admin is part of Ceph, a massively scalable, open-source,  dis‐
891       tributed  storage  system.   Please  refer to the Ceph documentation at
892       http://ceph.com/docs for more information.
893

SEE ALSO

895       ceph(8) radosgw(8)
896
898       2010-2021, Inktank Storage, Inc. and contributors. Licensed under  Cre‐
899       ative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0)
900
901
902
903
904dev                              May 13, 2021                 RADOSGW-ADMIN(8)
Impressum