From: Vinit Agnihotri Date: Thu, 13 Nov 2025 05:37:59 +0000 (+0530) Subject: docs-xml/manpages: Add man page for vfs_ceph_rgw X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=972e13fd7564dda5bb15c2dcee550f065474fb18;p=thirdparty%2Fsamba.git docs-xml/manpages: Add man page for vfs_ceph_rgw Document all module parameters. Signed-off-by: Vinit Agnihotri Reviewed-by: Shachar Sharon Reviewed-by: Anoop C S Reviewed-by: Guenther Deschner Autobuild-User(master): Anoop C S Autobuild-Date(master): Thu Jun 18 15:58:55 UTC 2026 on atb-devel-224 --- diff --git a/docs-xml/manpages/vfs_ceph_rgw.8.xml b/docs-xml/manpages/vfs_ceph_rgw.8.xml new file mode 100644 index 00000000000..c6d5d28053a --- /dev/null +++ b/docs-xml/manpages/vfs_ceph_rgw.8.xml @@ -0,0 +1,266 @@ + + + + + + vfs_ceph_rgw + 8 + Samba + System Administration tools + &doc.version; + + + + + vfs_ceph_rgw + + Use smb over object store provided by ceph librgw. + + + + + + vfs objects = ceph_rgw + + + + + DESCRIPTION + + This VFS module is part of the + samba + 8 suite. + + + The vfs_ceph_rgw VFS module exposes + ceph-rgw hosted s3 bucket to users. + + + + Ceph is a distributed network file system designed to provide + excellent performance, reliability, and scalability. + librgw is a shared library allowing applications to access an + object store i.e. s3 bucket via a posix-like interface. + + + + This module can not be combined with other modules. + + librgw does not support renaming directories. Therefore the module + internally ensures: + no + for Samba to not use temporary names while creating directory + and rename it to give name. + + librgw does not support random writes, therefore we do not implement + async io write methods. Therefore, the module internally ensures: + 0 + for samba to always use sync write method. + + + + + + + CONFIGURATION + + + vfs_ceph_rgw requires that the underlying + share path is a s3 bucket name. + + + + + ceph_rgw + / + + + + Since vfs_ceph_rgw does not require a + filesystem mount, the share / is treated + as root of the bucket and must be set to '/'. Any other path + is ignored. + In a ctdb cluster environment where ctdb manages Samba, + CTDB_SAMBA_SKIP_SHARE_CHECK=yes must be + configured to disable local share path checks, otherwise ctdb + will not reach a healthy state. + + + + + + OPTIONS + + + + + ceph_rgw:config_file = path + + + Allows one to define a ceph configuration to use. + (Required) + Default: + /etc/ceph/ceph.conf + + + Example: ceph_rgw:config_file = + /etc/ceph/ceph.conf + + + + + + ceph_rgw:keyring_file = path + + + Allows one to define a ceph keyring file to use. + (Required) + Default: + /etc/ceph/ceph.client.admin.keyring + + + Example: ceph_rgw:keyring_file = + /etc/ceph/ceph.client.admin.keyring + + + + + + ceph_rgw:user_id = name + + + User id of bucket owner + (Required) + + + Example: ceph_rgw:user_id = samba + + + + + + ceph_rgw:access_key = key + + + Access key for bucket owner specified by user_id option. + (Required) + + + Example: ceph_rgw:access_key = samba-key + + + + + + ceph_rgw:secret_access_key = key + + + Secret access key for bucket owner specified by user_id option. + (Required) + + + Example: ceph_rgw:secret_access_key = samba-secret-key + + + + + + ceph_rgw:bucket = bucket name + + + Bucket name to be exported as share. + (Required) + + + Example: ceph_rgw:bucket = video4k + + + + + + ceph_rgw:debug = boolean + + + Control debug logs for librgw + (Optional) + Default: off + + + Example: ceph_rgw:debug = on + + + + + + + + + + Sample configuration + + + One needs access to working ceph cluster to configure samba to use + this module. Following sample provides working samba configuration + for an already existing ceph rgw object store and has pre-existing + user, bucket and objects within bucket. + + + + Install librgw-devel package + + + clone samba sources + + + configure samba as compile with option "--enable-cephrgw" along with + usual configuration options. Compile and install. + + + + Edit smb.conf to include following share definition + Note: path must be set to '/', any other path is ignored. + + + + + rgw bucket + / + no + yes + ceph_rgw + my-bucket + user1 + user1passwd + user1passwd + /etc/ceph/ceph.conf + /etc/ceph/ceph.client.admin.keyring + off + + + + + Start samba server + + + + + + + VERSION + + + This man page is part of version &doc.version; of the Samba suite. + + + + + AUTHOR + + The original Samba software and related utilities + were created by Andrew Tridgell. Samba is now developed + by the Samba Team as an Open Source project similar + to the way the Linux kernel is developed. + + + + diff --git a/docs-xml/wscript_build b/docs-xml/wscript_build index 5d231ca1624..4d394d85cbd 100644 --- a/docs-xml/wscript_build +++ b/docs-xml/wscript_build @@ -82,6 +82,7 @@ vfs_module_manpages = ['vfs_acl_tdb', 'vfs_catia', 'vfs_ceph', 'vfs_ceph_new', + 'vfs_ceph_rgw', 'vfs_ceph_snapshots', 'vfs_commit', 'vfs_crossrename',