RADOSGW(8)

💖 RADOSGW(8) — the Ceph rados REST gateway, bestie edition 💖

okay so you're looking at the manual page for radosgw(8), which lives in the Ceph family of docs. yes, THAT Ceph. the massively scalable one. sit down, grab a strawberry 🍓, and let's get into it.

---

✨ NAME ✨

radosgw — the rados REST gateway. that's it, that's the name, and honestly? iconic. 👑

---

🦋 SYNOPSIS 🦋

radosgw

just... that. no flags required. she runs. 💅

---

🌸 DESCRIPTION 🌸

so radosgw is an HTTP REST gateway for the RADOS object store, which is itself a whole part of the Ceph distributed storage system. the way it's built? it's implemented as a FastCGI module</> using libfcgi, and you can pair it with literally any FastCGI capable web server. no cap. ✨

---

💜 OPTIONS 💜

• -c ceph.conf, --conf=ceph.conf — use ceph.conf as the config file instead of the default /etc/ceph/ceph.conf when figuring out monitor addresses at startup. lowkey important if your config lives somewhere else.
• -m monaddress[:port] — connect straight to the monitor you name (instead of digging through ceph.conf). shortcut energy. 🫶
• -i ID, --id ID — set the ID portion of name for radosgw.
• -n TYPE.ID, --name TYPE.ID — set the rados user name for the gateway, like for real, e.g. client.radosgw.gateway.
• --cluster NAME — set the cluster name (default: ceph). yes, the default is literally ceph.
• -d — run in the foreground, log to stderr. loud and proud. 📣
• -f — run in the foreground, log to the usual location. same vibe, tidier output spot.
• --rgw-region=region — the region where radosgw runs.
• --rgw-zone=zone — the zone where radosgw runs.

---

🎀 CONFIGURATION 🎀

the glow-up story

back in the day, RADOS Gateway had to be configured with Apache and mod_fastcgi. not anymore, bestie. now we use the mod_proxy_fcgi module instead of mod_fastcgi.

here's the thing though — mod_proxy_fcgi works differently than a traditional FastCGI module. it requires the service of mod_proxy, which is what actually provides support for the FastCGI protocol. so to handle the FastCGI protocol at all, both mod_proxy and mod_proxy_fcgi have to be present in the server. periodt.

and unlike mod_fastcgi, mod_proxy_fcgi cannot start the application process — she does not do that. 😭 some platforms have fcgistarter for that purpose. however, external launching of application or process management may be available in the FastCGI application framework in use.

Apache must be configured in a way that enables mod_proxy_fcgi to be used with localhost tcp.

the actual steps (localhost tcp edition) ✨

the following steps show the configuration in Ceph's configuration file, i.e. /etc/ceph/ceph.conf, and the gateway configuration file, i.e. /etc/httpd/conf.d/rgw.conf (RPM-based distros) or /etc/apache2/conf-available/rgw.conf (Debian-based distros), with localhost tcp:

1. for distros with Apache 2.2 and early versions of Apache 2.4 that use localhost TCP, append the following contents to /etc/ceph/ceph.conf:

[client.radosgw.gateway]
host = {hostname}
keyring = /etc/ceph/ceph.client.radosgw.keyring
log_file = /var/log/ceph/client.radosgw.gateway.log
rgw_frontends = fastcgi socket_port=9000 socket_host=0.0.0.0
rgw_print_continue = false

2. add the following content in the gateway configuration file:

for Debian/Ubuntu add in /etc/apache2/conf-available/rgw.conf:

<VirtualHost *:80>
ServerName localhost
DocumentRoot /var/www/html

ErrorLog /var/log/apache2/rgw_error.log
CustomLog /var/log/apache2/rgw_access.log combined

# LogLevel debug

RewriteEngine On

RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},L]

SetEnv proxy-nokeepalive 1

ProxyPass / fcgi://localhost:9000/

</VirtualHost>

for CentOS/RHEL add in /etc/httpd/conf.d/rgw.conf:

<VirtualHost *:80>
ServerName localhost
DocumentRoot /var/www/html

ErrorLog /var/log/httpd/rgw_error.log
CustomLog /var/log/httpd/rgw_access.log combined

# LogLevel debug

RewriteEngine On

RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},L]

SetEnv proxy-nokeepalive 1

ProxyPass / fcgi://localhost:9000/

</VirtualHost>

3. add the following content in the gateway configuration file:

for CentOS/RHEL add in /etc/httpd/conf.d/rgw.conf:

<VirtualHost *:80>
ServerName localhost
DocumentRoot /var/www/html

ErrorLog /var/log/httpd/rgw_error.log
CustomLog /var/log/httpd/rgw_access.log combined

# LogLevel debug

RewriteEngine On

RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},L]

SetEnv proxy-nokeepalive 1

ProxyPass / unix:///var/run/ceph/ceph.radosgw.gateway.fastcgi.sock|fcgi://localhost:9000/

</VirtualHost>

4. generate a key for radosgw to use for authentication with the cluster.

ceph-authtool -C -n client.radosgw.gateway --gen-key /etc/ceph/keyring.radosgw.gateway
ceph-authtool -n client.radosgw.gateway --cap mon 'allow rw' --cap osd 'allow rwx' /etc/ceph/keyring.radosgw.gateway

5. add the key to the auth entries.

ceph auth add client.radosgw.gateway --in-file=keyring.radosgw.gateway

6. start Apache and radosgw.

Debian/Ubuntu:

sudo /etc/init.d/apache2 start
sudo /etc/init.d/radosgw start

CentOS/RHEL:

sudo apachectl start
sudo /etc/init.d/ceph-radosgw start

---

🌈 USAGE LOGGING 🌈

radosgw maintains an asynchronous usage log. she's out here accumulating statistics about user operations and flushing it periodically. you can access and manage these logs through radosgw-admin.

the info being logged contains total data transfer, total operations, and total successful operations. the data is accounted in an hourly resolution under the bucket owner — unless the operation was done on the service (e.g., when listing a bucket), in which case it's accounted under the operating user. yes, the plot twist matters. 💀

here's an example configuration:

[client.radosgw.gateway]
    rgw_enable_usage_log = true
    rgw_usage_log_tick_interval = 30
    rgw_usage_log_flush_threshold = 1024
    rgw_usage_max_shards = 32
    rgw_usage_max_user_shards = 1

the total number of shards determines how many total objects hold the usage log information. the per-user number of shards specifies how many objects hold usage information for a single user. the tick interval configures the number of seconds between log flushes, and the flush threshold specifies how many entries can be kept before resorting to synchronous flush. so many shards. so much control. 🧚

---

⭐ AVAILABILITY ⭐

radosgw is part of Ceph, a massively scalable, open-source, distributed storage system. please refer to the Ceph documentation at <https://docs.ceph.com> for more information.

---

👑 SEE ALSO 👑

ceph(8), radosgw-admin(8)

---

💖 Copyright 💖

2010-2014, Inktank Storage, Inc. and contributors. Licensed under Creative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0)

---

okay that's the whole thing, bestie. this page came out of the dev branch, dated Aug 19, 2026, and it's filed under RADOSGW(8). go forth and gateway. 💅✨🦋