VFS_CEPH_RGW(8)

NAME
vfs_ceph_rgw - Use smb over object store provided by ceph librgw.

SYNOPSIS

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: vfs mkdir use tmp name = 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: aio write size = 0 for samba to always use sync write method.

CONFIGURATION

vfs_ceph_rgw requires that the underlying share path is a s3 bucket name.

    		[share]
    		vfs objects = ceph_rgw
    		path = /

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.

GLOBAL OPTIONS

The following options must be set in the global smb.conf section and won't take effect when set per share. librgw can only be initialised once per process, so these parameters are shared across all shares.

ceph_rgw:id = name
    Client id portion of the Ceph client name used by librgw. (Required)

    Example: ceph_rgw:id = admin

ceph_rgw:config_file = path
    Allows one to define a ceph configuration to use. 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)

    Example: ceph_rgw:keyring_file = /etc/ceph/ceph.client.admin.keyring

ceph_rgw:debug = boolean
    Control debug logs for librgw. Default: off

    Example: ceph_rgw:debug = on

OPTIONS

The following options can be set per share.

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

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.

        1. Install librgw-devel package

        2. clone samba sources

        3. configure samba as compile with option "--enable-cephrgw" along with usual configuration options. Compile and install.

        4. Edit smb.conf to include following share definition Note: path must be set to '/', any other path is ignored.

            			[global]
            			ceph_rgw:id = admin
            			ceph_rgw:config_file = /etc/ceph/ceph.conf
            			ceph_rgw:keyring_file = /etc/ceph/ceph.client.admin.keyring

            			[share]
            			comment = rgw bucket
            			path = /
            			read only = no
            			inherit permissions = yes
            			vfs objects = ceph_rgw
            			ceph_rgw:bucket = my-bucket
            			ceph_rgw:user_id = user1
            			ceph_rgw:access_key = user1passwd
            			ceph_rgw:secret_access_key = user1passwd

        5. Start samba server

VERSION

This man page is part of version 4.25.0rc1 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.