Admin Guide

Once you have your Ceph Object Storage service up and running, you mayadminister the service with user management, access controls, quotasand usage tracking among other features.

User Management

Ceph Object Storage user management refers to users of the Ceph Object Storageservice (i.e., not the Ceph Object Gateway as a user of the Ceph StorageCluster). You must create a user, access key and secret to enable end users tointeract with Ceph Object Gateway services.

There are two user types:

  • User: The term ‘user’ reflects a user of the S3 interface.

  • Subuser: The term ‘subuser’ reflects a user of the Swift interface. A subuseris associated to a user .

Admin Guide - 图1

You can create, modify, view, suspend and remove users and subusers. In additionto user and subuser IDs, you may add a display name and an email address for auser. You can specify a key and secret, or generate a key and secretautomatically. When generating or specifying keys, note that user IDs correspondto an S3 key type and subuser IDs correspond to a swift key type. Swift keysalso have access levels of read, write, readwrite and full.

Create a User

To create a user (S3 interface), execute the following:

  1. radosgw-admin user create --uid={username} --display-name="{display-name}" [--email={email}]

For example:

  1. radosgw-admin user create --uid=johndoe --display-name="John Doe" --email=john@example.com
  1. { "user_id": "johndoe",
  2.   "display_name": "John Doe",
  3.   "email": "john@example.com",
  4.   "suspended": 0,
  5.   "max_buckets": 1000,
  6.   "subusers": [],
  7.   "keys": [
  8.         { "user": "johndoe",
  9.           "access_key": "11BS02LGFB6AL6H1ADMW",
  10.           "secret_key": "vzCEkuryfn060dfee4fgQPqFrncKEIkh3ZcdOANY"}],
  11.   "swift_keys": [],
  12.   "caps": [],
  13.   "op_mask": "read, write, delete",
  14.   "default_placement": "",
  15.   "placement_tags": [],
  16.   "bucket_quota": { "enabled": false,
  17.       "max_size_kb": -1,
  18.       "max_objects": -1},
  19.   "user_quota": { "enabled": false,
  20.       "max_size_kb": -1,
  21.       "max_objects": -1},
  22.   "temp_url_keys": []}

Creating a user also creates an access_key and secret_key entry for usewith any S3 API-compatible client.

Important

Check the key output. Sometimes radosgw-admingenerates a JSON escape (\) character, and some clientsdo not know how to handle JSON escape characters. Remedies includeremoving the JSON escape character (\), encapsulating the stringin quotes, regenerating the key and ensuring that itdoes not have a JSON escape character or specify the key and secretmanually.

Create a Subuser

To create a subuser (Swift interface) for the user, you must specify the user ID(—uid={username}), a subuser ID and the access level for the subuser.

  1. radosgw-admin subuser create --uid={uid} --subuser={uid} --access=[ read | write | readwrite | full ]

For example:

  1. radosgw-admin subuser create --uid=johndoe --subuser=johndoe:swift --access=full

Note

full is not readwrite, as it also includes the access control policy.

  1. { "user_id": "johndoe",
  2.   "display_name": "John Doe",
  3.   "email": "john@example.com",
  4.   "suspended": 0,
  5.   "max_buckets": 1000,
  6.   "subusers": [
  7.         { "id": "johndoe:swift",
  8.           "permissions": "full-control"}],
  9.   "keys": [
  10.         { "user": "johndoe",
  11.           "access_key": "11BS02LGFB6AL6H1ADMW",
  12.           "secret_key": "vzCEkuryfn060dfee4fgQPqFrncKEIkh3ZcdOANY"}],
  13.   "swift_keys": [],
  14.   "caps": [],
  15.   "op_mask": "read, write, delete",
  16.   "default_placement": "",
  17.   "placement_tags": [],
  18.   "bucket_quota": { "enabled": false,
  19.       "max_size_kb": -1,
  20.       "max_objects": -1},
  21.   "user_quota": { "enabled": false,
  22.       "max_size_kb": -1,
  23.       "max_objects": -1},
  24.   "temp_url_keys": []}

Get User Info

To get information about a user, you must specify user info and the user ID(—uid={username}) .

  1. radosgw-admin user info --uid=johndoe

Modify User Info

To modify information about a user, you must specify the user ID (—uid={username})and the attributes you want to modify. Typical modifications are to keys and secrets,email addresses, display names and access levels. For example:

  1. radosgw-admin user modify --uid=johndoe --display-name="John E. Doe"

To modify subuser values, specify subuser modify, user ID and the subuser ID. For example:

  1. radosgw-admin subuser modify --uid=johndoe --subuser=johndoe:swift --access=full

User Enable/Suspend

When you create a user, the user is enabled by default. However, you may suspenduser privileges and re-enable them at a later time. To suspend a user, specifyuser suspend and the user ID.

  1. radosgw-admin user suspend --uid=johndoe

To re-enable a suspended user, specify user enable and the user ID.

  1. radosgw-admin user enable --uid=johndoe

Note

Disabling the user disables the subuser.

Remove a User

When you remove a user, the user and subuser are removed from the system.However, you may remove just the subuser if you wish. To remove a user (andsubuser), specify user rm and the user ID.

  1. radosgw-admin user rm --uid=johndoe

To remove the subuser only, specify subuser rm and the subuser ID.

  1. radosgw-admin subuser rm --subuser=johndoe:swift

Options include:

  • Purge Data: The —purge-data option purges all data associatedto the UID.

  • Purge Keys: The —purge-keys option purges all keys associatedto the UID.

Remove a Subuser

When you remove a sub user, you are removing access to the Swift interface.The user will remain in the system. To remove the subuser, specifysubuser rm and the subuser ID.

  1. radosgw-admin subuser rm --subuser=johndoe:swift

Options include:

  • Purge Keys: The —purge-keys option purges all keys associatedto the UID.

Add / Remove a Key

Both users and subusers require the key to access the S3 or Swift interface. Touse S3, the user needs a key pair which is composed of an access key and asecret key. On the other hand, to use Swift, the user typically needs a secretkey (password), and use it together with the associated user ID. You may createa key and either specify or generate the access key and/or secret key. You mayalso remove a key. Options include:

  • —key-type=<type> specifies the key type. The options are: s3, swift

  • —access-key=<key> manually specifies an S3 access key.

  • —secret-key=<key> manually specifies a S3 secret key or a Swift secret key.

  • —gen-access-key automatically generates a random S3 access key.

  • —gen-secret automatically generates a random S3 secret key or a random Swift secret key.

An example how to add a specified S3 key pair for a user.

  1. radosgw-admin key create --uid=foo --key-type=s3 --access-key fooAccessKey --secret-key fooSecretKey
  1. { "user_id": "foo",
  2.   "rados_uid": 0,
  3.   "display_name": "foo",
  4.   "email": "foo@example.com",
  5.   "suspended": 0,
  6.   "keys": [
  7.     { "user": "foo",
  8.       "access_key": "fooAccessKey",
  9.       "secret_key": "fooSecretKey"}],
  10. }

Note that you may create multiple S3 key pairs for a user.

To attach a specified swift secret key for a subuser.

  1. radosgw-admin key create --subuser=foo:bar --key-type=swift --secret-key barSecret
  1. { "user_id": "foo",
  2.   "rados_uid": 0,
  3.   "display_name": "foo",
  4.   "email": "foo@example.com",
  5.   "suspended": 0,
  6.   "subusers": [
  7.      { "id": "foo:bar",
  8.        "permissions": "full-control"}],
  9.   "swift_keys": [
  10.     { "user": "foo:bar",
  11.       "secret_key": "asfghjghghmgm"}]}

Note that a subuser can have only one swift secret key.

Subusers can also be used with S3 APIs if the subuser is associated with a S3 key pair.

  1. radosgw-admin key create --subuser=foo:bar --key-type=s3 --access-key barAccessKey --secret-key barSecretKey
  1. { "user_id": "foo",
  2.   "rados_uid": 0,
  3.   "display_name": "foo",
  4.   "email": "foo@example.com",
  5.   "suspended": 0,
  6.   "subusers": [
  7.      { "id": "foo:bar",
  8.        "permissions": "full-control"}],
  9.   "keys": [
  10.     { "user": "foo:bar",
  11.       "access_key": "barAccessKey",
  12.       "secret_key": "barSecretKey"}],
  13. }

To remove a S3 key pair, specify the access key.

  1. radosgw-admin key rm --uid=foo --key-type=s3 --access-key=fooAccessKey

To remove the swift secret key.

  1. radosgw-admin key rm -subuser=foo:bar --key-type=swift

Add / Remove Admin Capabilities

The Ceph Storage Cluster provides an administrative API that enables users toexecute administrative functions via the REST API. By default, users do NOT haveaccess to this API. To enable a user to exercise administrative functionality,provide the user with administrative capabilities.

To add administrative capabilities to a user, execute the following:

  1. radosgw-admin caps add --uid={uid} --caps={caps}

You can add read, write or all capabilities to users, buckets, metadata andusage (utilization). For example:

  1. --caps="[users|buckets|metadata|usage|zone]=[*|read|write|read, write]"

For example:

  1. radosgw-admin caps add --uid=johndoe --caps="users=*;buckets=*"

To remove administrative capabilities from a user, execute the following:

  1. radosgw-admin caps rm --uid=johndoe --caps={caps}

Quota Management

The Ceph Object Gateway enables you to set quotas on users and buckets owned byusers. Quotas include the maximum number of objects in a bucket and the maximumstorage size a bucket can hold.

  • Bucket: The —bucket option allows you to specify a quota forbuckets the user owns.

  • Maximum Objects: The —max-objects setting allows you to specifythe maximum number of objects. A negative value disables this setting.

  • Maximum Size: The —max-size option allows you to specify a quotasize in B/K/M/G/T, where B is the default. A negative value disables this setting.

  • Quota Scope: The —quota-scope option sets the scope for the quota.The options are bucket and user. Bucket quotas apply to buckets auser owns. User quotas apply to a user.

Set User Quota

Before you enable a quota, you must first set the quota parameters.For example:

  1. radosgw-admin quota set --quota-scope=user --uid=<uid> [--max-objects=<num objects>] [--max-size=<max size>]

For example:

  1. radosgw-admin quota set --quota-scope=user --uid=johndoe --max-objects=1024 --max-size=1024B

A negative value for num objects and / or max size means that thespecific quota attribute check is disabled.

Enable/Disable User Quota

Once you set a user quota, you may enable it. For example:

  1. radosgw-admin quota enable --quota-scope=user --uid=<uid>

You may disable an enabled user quota. For example:

  1. radosgw-admin quota disable --quota-scope=user --uid=<uid>

Set Bucket Quota

Bucket quotas apply to the buckets owned by the specified uid. They areindependent of the user.

  1. radosgw-admin quota set --uid=<uid> --quota-scope=bucket [--max-objects=<num objects>] [--max-size=<max size]

A negative value for num objects and / or max size means that thespecific quota attribute check is disabled.

Enable/Disable Bucket Quota

Once you set a bucket quota, you may enable it. For example:

  1. radosgw-admin quota enable --quota-scope=bucket --uid=<uid>

You may disable an enabled bucket quota. For example:

  1. radosgw-admin quota disable --quota-scope=bucket --uid=<uid>

Get Quota Settings

You may access each user’s quota settings via the user informationAPI. To read user quota setting information with the CLI interface,execute the following:

  1. radosgw-admin user info --uid=<uid>

Update Quota Stats

Quota stats get updated asynchronously. You can update quotastatistics for all users and all buckets manually to retrievethe latest quota stats.

  1. radosgw-admin user stats --uid=<uid> --sync-stats

Get User Usage Stats

To see how much of the quota a user has consumed, execute the following:

  1. radosgw-admin user stats --uid=<uid>

Note

You should execute radosgw-admin user stats with the—sync-stats option to receive the latest data.

Default Quotas

You can set default quotas in the config. These defaults are used whencreating a new user and have no effect on existing users. If therelevant default quota is set in config, then that quota is set on thenew user, and that quota is enabled. See rgw bucket default quota max objects,rgw bucket default quota max size, rgw user default quota max objects, andrgw user default quota max size in Ceph Object Gateway Config Reference

Quota Cache

Quota statistics are cached on each RGW instance. If there are multipleinstances, then the cache can keep quotas from being perfectly enforced, aseach instance will have a different view of quotas. The options that controlthis are rgw bucket quota ttl, rgw user quota bucket sync interval andrgw user quota sync interval. The higher these values are, the moreefficient quota operations are, but the more out-of-sync multiple instanceswill be. The lower these values are, the closer to perfect enforcementmultiple instances will achieve. If all three are 0, then quota caching iseffectively disabled, and multiple instances will have perfect quotaenforcement. See Ceph Object Gateway Config Reference

Reading / Writing Global Quotas

You can read and write global quota settings in the period configuration. Toview the global quota settings:

  1. radosgw-admin global quota get

The global quota settings can be manipulated with the global quotacounterparts of the quota set, quota enable, and quota disablecommands.

  1. radosgw-admin global quota set --quota-scope bucket --max-objects 1024
  2. radosgw-admin global quota enable --quota-scope bucket

Note

In a multisite configuration, where there is a realm and periodpresent, changes to the global quotas must be committed using periodupdate —commit. If there is no period present, the rados gateway(s) mustbe restarted for the changes to take effect.

Usage

The Ceph Object Gateway logs usage for each user. You can trackuser usage within date ranges too.

  • Add rgw enable usage log = true in [client.rgw] section of ceph.conf and restart the radosgw service.

Options include:

  • Start Date: The —start-date option allows you to filter usagestats from a particular start date (format: yyyy-mm-dd[HH:MM:SS]).

  • End Date: The —end-date option allows you to filter usage upto a particular date (format: yyyy-mm-dd[HH:MM:SS]).

  • Log Entries: The —show-log-entries option allows you to specifywhether or not to include log entries with the usage stats(options: true | false).

Note

You may specify time with minutes and seconds, but it is storedwith 1 hour resolution.

Show Usage

To show usage statistics, specify the usage show. To show usage for aparticular user, you must specify a user ID. You may also specify a start date,end date, and whether or not to show log entries.:

  1. radosgw-admin usage show --uid=johndoe --start-date=2012-03-01 --end-date=2012-04-01

You may also show a summary of usage information for all users by omitting a user ID.

  1. radosgw-admin usage show --show-log-entries=false

Trim Usage

With heavy use, usage logs can begin to take up storage space. You can trimusage logs for all users and for specific users. You may also specify dateranges for trim operations.

  1. radosgw-admin usage trim --start-date=2010-01-01 --end-date=2010-12-31
  2. radosgw-admin usage trim --uid=johndoe
  3. radosgw-admin usage trim --uid=johndoe --end-date=2013-12-31