Ceph is an enterprise-grade, and open-source software-defined storage solution backed by Red Hat. It is designed for reliability, scalability, and high performance. Ceph unifies block, file, and object storage into a single distributes storage system with common management, seamless scalability, and no single point of failure. Ceph is commonly used in enterprise storage solutions, production cloud infrastructures, and all kinds of deployments with heavy requirements of scalable storage.

In a Ceph object storage deployment using the RADOS Gateway (RGW), radosgw-admin is a powerful tool that allows you to manage users and buckets directly from the command line. This can be useful for scripting, automation, and troubleshooting purposes.

One important component of Ceph is the RADOS Gateway (RGW), which exposes object storage via the following interfaces:

• S3-compatible: Provides object storage functionality with an interface that is compatible with a large subset of the Amazon S3 RESTful API.
• Swift-compatible: Provides object storage functionality with an interface that is compatible with a large subset of the OpenStack Swift API.

In this tutorial, we cover the usage of Ceph’s RGW administrative CLI to create users, generate access keys, create buckets, and how to upload or download data from the bucket.

If you are using Rook-Ceph, check out the article below:

• Create and Write to an S3 Bucket with Rook-Ceph

Prerequisites

• A fully functional Ceph cluster with RADOS Gateway (RGW) enabled.
• Access to a ceph storage node with radosgw-admin installed and with proper permissions to run the tool.
• Ceph cluster admin privileges for performing operations

Verify Ceph is installed by checking version:

$ ceph -v
ceph version 19.2.0 (16063ff2022298c9300e49a547a16ffda59baf13) squid (stable)

Also query cluster status:

$ ceph -s
  cluster:
    id:     55ba9087-4ef0-422c-b60d-e8a018e9142b
    health: HEALTH_OK
  
  services:
    mon: 3 daemons, quorum a,b,c (age 4w)
    mgr: a(active, since 4w), standbys: b
    mds: 1/1 daemons up, 1 hot standby
    osd: 6 osds: 6 up (since 4w), 6 in (since 4w)
    rgw: 1 daemon active (1 hosts, 1 zones)

  data:
    volumes: 1/1 healthy
    pools:   12 pools, 393 pgs
    objects: 670 objects, 380 MiB
    usage:   7.7 GiB used, 592 GiB / 600 GiB avail
    pgs:     393 active+clean

  io:
    client:   4.9 KiB/s rd, 170 B/s wr, 5 op/s rd, 2 op/s wr

Create a Ceph Object Store User

We need to create a user, access key, and secret key to enable end users to interact with Ceph Object Gateway services.

The command for creating user is:

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

Here is an example:

radosgw-admin user create \
  --uid="s3demo-user" \
  --display-name="S3 DemoUser" \
  --email="[email protected]"

Sample output:

{
    "user_id": "s3demo-user",
    "display_name": "S3 DemoUser",
    "email": "[email protected]",
    "suspended": 0,
    "max_buckets": 1000,
    "subusers": [],
    "keys": [
        {
            "user": "s3demo-user",
            "access_key": "P1ZP4WJ573B6LZMCIKVW",
            "secret_key": "TiDDV4aGv4rWJYsc6dglINW3v8j0DycfdvZAep3z",
            "active": true,
            "create_date": "2025-04-11T09:04:46.923294Z"
        }
    ],
    "swift_keys": [],
    "caps": [],
    "op_mask": "read, write, delete",
    "default_placement": "",
    "default_storage_class": "",
    "placement_tags": [],
    "bucket_quota": {
        "enabled": false,
        "check_on_raw": false,
        "max_size": -1,
        "max_size_kb": 0,
        "max_objects": -1
    },
    "user_quota": {
        "enabled": false,
        "check_on_raw": false,
        "max_size": -1,
        "max_size_kb": 0,
        "max_objects": -1
    },
    "temp_url_keys": [],
    "type": "rgw",
    "mfa_ids": [],
    "account_id": "",
    "path": "/",
    "create_date": "2025-04-11T09:04:46.922695Z",
    "tags": [],
    "group_ids": []
}

When a user is created, the access_key and a secret_key entries are also generated, which can be used with any S3 API-compatible client.

"keys": [
        {
            "user": "s3demo-user",
            "access_key": "P1ZP4WJ573B6LZMCIKVW",
            "secret_key": "TiDDV4aGv4rWJYsc6dglINW3v8j0DycfdvZAep3z",
            "active": true,
            "create_date": "2025-04-11T09:04:46.923294Z"
        }

Save these details as will be used later to connect to RGW and manage buckets.

Displaying user information

At any time, you can retrieve user information by executing:

radosgw-admin user info --uid=<username>

Example:

$ radosgw-admin user info --uid=s3demo-user
{
    "user_id": "s3demo-user",
    "display_name": "S3 DemoUser",
    "email": "[email protected]",
    "suspended": 0,
    "max_buckets": 1000,
    "subusers": [],
    "keys": [
        {
            "user": "s3demo-user",
            "access_key": "P1ZP4WJ573B6LZMCIKVW",
            "secret_key": "TiDDV4aGv4rWJYsc6dglINW3v8j0DycfdvZAep3z",
            "active": true,
            "create_date": "2025-04-11T09:04:46.923294Z"
        }
    ],
    "swift_keys": [],
    "caps": [],
    "op_mask": "read, write, delete",
    "default_placement": "",
    "default_storage_class": "",
    "placement_tags": [],
    "bucket_quota": {
        "enabled": false,
        "check_on_raw": false,
        "max_size": -1,
        "max_size_kb": 0,
        "max_objects": -1
    },
    "user_quota": {
        "enabled": false,
        "check_on_raw": false,
        "max_size": -1,
        "max_size_kb": 0,
        "max_objects": -1
    },
    "temp_url_keys": [],
    "type": "rgw",
    "mfa_ids": [],
    "account_id": "",
    "path": "/",
    "create_date": "2025-04-11T09:04:46.922695Z",
    "tags": [],
    "group_ids": []
}

Quota Management for a user / bucket

The Ceph Object Gateway allows you to set quotas on users and their buckets. This include limits on total storage size each bucket can use, and the number of objects.

• Bucket: The --bucket option lets you set a quota for the buckets owned by the user.
• Maximum Objects: The --max-objects option specifies the maximum number of objects allowed. Setting a negative value disables the limit.”
• Maximum Size: The –quota-scope option defines the scope of the quota. Available values are bucket and user. Bucket quotas apply to each individual bucket, while user quotas are aggregated across all buckets owned by the user.

Here is the command syntax for setting quotas:

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

As an example, let us set some quotas for our demo user:

radosgw-admin quota set \
--quota-scope=user \
--uid=s3demo-user \
--max-size=20G

After setting a user quota, you must enable it for it to take effect.

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

Example:

radosgw-admin quota enable --quota-scope=user --uid=s3demo-user

When you check the user information, it should display quotas as enabled under user_quota.

$ radosgw-admin user info --uid=s3demo-user
{
    "user_id": "s3demo-user",
    "display_name": "S3 DemoUser",
    "email": "[email protected]",
    "suspended": 0,
    "max_buckets": 1000,
    "subusers": [],
...
    "user_quota": {
        "enabled": true,
        "check_on_raw": false,
        "max_size": 21474836480,
        "max_size_kb": 20971520,
        "max_objects": -1
    },
}

To disable an active user quota, run a command in the following format:

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

Create a Bucket for the User

After the user is created with access credentials, use an S3-compatible tool like s5cmd, awscli, or boto3 and provide the credentials for bucket creation.

• How To Install and use s5cmd

Create ~/.aws directory if doesn’t exist already:

mkdir ~/.aws

Then create a file that will store credentials:

vim ~/.aws/credentials

Create a custom ceph profile. For example:

[ceph]
aws_access_key_id = P1ZP4WJ573B6LZMCIKVW
aws_secret_access_key = TiDDV4aGv4rWJYsc6dglINW3v8j0DycfdvZAep3z

To set as default, use:

[default]
aws_access_key_id = <AWS_ACCESS_KEY_ID>
aws_secret_access_key = <AWS_SECRET_ACCESS_KEY>

You can also export the credentials as environment variables if you prefer not to store them in a file.

export AWS_ACCESS_KEY_ID=P1ZP4WJ573B6LZMCIKVW
export AWS_SECRET_ACCESS_KEY=TiDDV4aGv4rWJYsc6dglINW3v8j0DycfdvZAep3z

In our setup, the RADOS Gateway is accessible at http://192.168.20.15. To create a bucket, run the following command:

export S3_HOST=http://192.168.20.15
export BUCKET_NAME=mybucketest1
s5cmd --endpoint-url $S3_HOST mb s3://$BUCKET_NAME

If using profile, pass it like below:

s5cmd --profile ceph --endpoint-url $S3_HOST mb s3://$BUCKET_NAME

Expected command output:

mb s3://mybucketest1

Check out our s5cmd guide for detailed instructions with examples.