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.  If a bucket is specified (e.g., via
358              --bucket_id  or  via  --bucket and optional --tenant), only that
359              bucket is processed.
360
361       metadata get
362              Get metadata info.
363
364       metadata put
365              Put metadata info.
366
367       metadata rm
368              Remove metadata info.
369
370       metadata list
371              List metadata info.
372
373       mdlog list
374              List metadata log which is needed for multi-site deployments.
375
376       mdlog trim
377              Trim metadata log manually instead of relying on RGWs integrated
378              log  sync.   Before trimming, compare the listings and make sure
379              the last sync was complete, otherwise it can reinitiate a sync.
380
381       mdlog status
382              Read metadata log status.
383
384       bilog list
385              List bucket index log which is  needed  for  multi-site  deploy‐
386              ments.
387
388       bilog trim
389              Trim  bucket  index  log (use start-marker, end-marker) manually
390              instead of relying on RGWs integrated log  sync.   Before  trim‐
391              ming,  compare the listings and make sure the last sync was com‐
392              plete, otherwise it can reinitiate a sync.
393
394       datalog list
395              List data log which is needed for multi-site deployments.
396
397       datalog trim
398              Trim data log manually instead of relying on RGWs integrated log
399              sync.   Before  trimming, compare the listings and make sure the
400              last sync was complete, otherwise it can reinitiate a sync.
401
402       datalog status
403              Read data log status.
404
405       orphans find
406              Init and run search for leaked rados objects.   DEPRECATED.  See
407              the "rgw-orphan-list" tool.
408
409       orphans finish
410              Clean  up  search for leaked rados objects.  DEPRECATED. See the
411              "rgw-orphan-list" tool.
412
413       orphans list-jobs
414              List the current job-ids for the  orphans  search.   DEPRECATED.
415              See the "rgw-orphan-list" tool.
416
417       role create
418              create a new AWS role for use with STS.
419
420       role rm
421              Remove a role.
422
423       role get
424              Get a role.
425
426       role list
427              List the roles with specified path prefix.
428
429       role modify
430              Modify the assume role policy of an existing role.
431
432       role-policy put
433              Add/update permission policy to role.
434
435       role-policy list
436              List the policies attached to a role.
437
438       role-policy get
439              Get the specified inline policy document embedded with the given
440              role.
441
442       role-policy rm
443              Remove the policy attached to a role
444
445       reshard add
446              Schedule a resharding of a bucket
447
448       reshard list
449              List all bucket resharding or scheduled to be resharded
450
451       reshard process
452              Process of scheduled reshard jobs
453
454       reshard status
455              Resharding status of a bucket
456
457       reshard cancel
458              Cancel resharding a bucket
459
460       topic list
461              List bucket notifications/pubsub topics
462
463       topic get
464              Get a bucket notifications/pubsub topic
465
466       topic rm
467              Remove a bucket notifications/pubsub topic
468
469       subscription get
470              Get a pubsub subscription definition
471
472       subscription rm
473              Remove a pubsub subscription
474
475       subscription pull
476              Show events in a pubsub subscription
477
478       subscription ack
479              Ack (remove) an events in a pubsub subscription
480

OPTIONS

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

QUOTA OPTIONS

779       --max-objects
780              Specify max objects (negative value to disable).
781
782       --max-size
783              Specify max size (in B/K/M/G/T, negative value to disable).
784
785       --quota-scope
786              The scope of quota (bucket, user).
787

ORPHANS SEARCH OPTIONS

789       --num-shards
790              Number of shards to use for keeping the temporary scan info
791
792       --orphan-stale-secs
793              Number  of  seconds  to wait before declaring an object to be an
794              orphan.  Default is 86400 (24 hours).
795
796       --job-id
797              Set the job id (for orphans find)
798

ORPHANS LIST-JOBS OPTIONS

800       --extra-info
801              Provide extra info in the job list.
802

ROLE OPTIONS

804       --role-name
805              The name of the role to create.
806
807       --path The path to the role.
808
809       --assume-role-policy-doc
810              The trust relationship policy document  that  grants  an  entity
811              permission to assume the role.
812
813       --policy-name
814              The name of the policy document.
815
816       --policy-doc
817              The permission policy document.
818
819       --path-prefix
820              The path prefix for filtering the roles.
821

BUCKET NOTIFICATIONS/PUBSUB OPTIONS

823       --topic
824              The bucket notifications/pubsub topic name.
825
826       --subscription
827              The pubsub subscription name.
828
829       --event-id
830              The event id in a pubsub subscription.
831

EXAMPLES

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

AVAILABILITY

903       radosgw-admin is part of Ceph, a massively scalable, open-source,  dis‐
904       tributed  storage  system.   Please  refer to the Ceph documentation at
905       https://docs.ceph.com for more information.
906

SEE ALSO

908       ceph(8) radosgw(8)
909
911       2010-2022, Inktank Storage, Inc. and contributors. Licensed under  Cre‐
912       ative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0)
913
914
915
916
917dev                              Oct 18, 2022                 RADOSGW-ADMIN(8)
Impressum