The Ganesha Library provides base classes that can be used by drivers to provision shares via NFS (NFSv3 and NFSv4), utilizing the NFS-Ganesha NFS server.
ganesha.GaneshaNASHelper2
library classganesha.GaneshaNASHelper
library classPreferred:
NFS-Ganesha v2.4 or
later, which allows dynamic update of access rules. Use with manila’s
ganesha.GaneshaNASHelper2
class as described later in
Using Ganesha Library in drivers.
(or)
NFS-Ganesha v2.5.4 or
later that allows dynamic update of access rules, and can make use of highly
available Ceph RADOS (distributed object storage) as its shared storage for
NFS client recovery data, and exports. Use with Ceph v12.2.2 or later, and
ganesha.GaneshaNASHelper2
library class in manila Queens release or
later.
For use with limitations documented in Known Issues:
NFS-Ganesha v2.1 to
v2.3. Use with manila’s ganesha.GaneshaNASHelper
class as described later
in Using Ganesha Library in drivers.
The library has just modest requirements against general NFS-Ganesha (in the following: Ganesha) configuration; a best effort was made to remain agnostic towards it as much as possible. This section describes the few requirements.
Note that Ganesha’s concept of storage backend modules is called FSAL (“File System Abstraction Layer”). The FSAL the driver intends to leverage needs to be enabled in Ganesha config.
Beyond that (with default manila config) the following line is needed to be present in the Ganesha config file (that defaults to /etc/ganesha/ganesha.conf):
%include /etc/ganesha/export.d/INDEX.conf
The above paths can be customized through manila configuration as follows:
defaults to /etc/ganesha
to ganesha.conf in ganesha_config_dir
stored, defaults to export.d in ganesha_config_dir. The following line is required to be included (with value expanded) in the Ganesha config file (at ganesha_config_path):
%include <ganesha_export_dir>/INDEX.conf
In versions 2.5.4 or later, Ganesha can store NFS client recovery data in Ceph RADOS, and also read exports stored in Ceph RADOS. These features are useful to make Ganesha server that has access to a Ceph (luminous or later) storage backend, highly available. The Ganesha library class GaneshaNASHelper2 (in manila Queens or later) allows you to store Ganesha exports directly in a shared storage, RADOS objects, by setting the following manila config options in the driver section:
Check out the cephfs_driver documentation for an example driver section that uses these options.
To allow Ganesha to read from RADOS objects add the below code block in ganesha’s configuration file, substituting values per your setup.
# To read exports from RADOS objects
RADOS_URLS {
ceph_conf = "/etc/ceph/ceph.conf";
userid = "admin";
}
# Replace with actual pool name, and export index object
%url rados://<ganesha_rados_store_pool_name>/<ganesha_rados_export_index>
# To store client recovery data in the same RADOS pool
NFSv4 {
RecoveryBackend = "rados_kv";
}
RADOS_KV {
ceph_conf = "/etc/ceph/ceph.conf";
userid = "admin";
# Replace with actual pool name
pool = <ganesha_rados_store_pool_name>;
}
For a fresh setup, make sure to create the Ganesha export index object as an empty object before starting the Ganesha server.
echo | sudo rados -p ${GANESHA_RADOS_STORE_POOL_NAME} put ganesha-export-index -
A driver that wants to use the Ganesha Library has to inherit
from driver.GaneshaMixin
.
The driver has to contain a subclass of ganesha.GaneshaNASHelper2
,
instantiate it along with the driver instance and delegate
update_access
method to it (when appropriate, i.e., when access_proto
is NFS).
Note
You can also subclass ganesha.GaneshaNASHelper
. It works with
NFS-Ganesha v2.1 to v2.3 that doesn’t support dynamic update of exports.
To update access rules without having to restart NFS-Ganesha server, the
class manipulates exports created per share access rule (rather than per
share) introducing limitations documented in Known Issues.
In the following we explain what has to be implemented by the
ganesha.GaneshaNASHelper2
subclass (to which we refer as “helper
class”).
Ganesha exports are described by so-called Ganesha export blocks (introduced in the 2.* release series), that is, snippets of Ganesha config specifying key-pair values.
The Ganesha Library generates sane default export blocks for the
exports it manages, with one thing left blank, the so-called FSAL
subblock. The helper class has to implement the _fsal_hook
method which returns the FSAL subblock (in Python represented as
a dict with string keys and values). It has one mandatory key,
Name
, to which the value should be the name of the FSAL
(eg.: {"Name": "CEPH"}
). Further content of it is
optional and FSAL specific.
As noted, the Ganesha Library provides sane general defaults.
However, the driver is allowed to:
The config format for Ganesha Library is called export block
template. They are syntactically either Ganesha export blocks,
(please consult the Ganesha documentation about the format),
or isomorphic JSON (as Ganesha export blocks are by-and-large
equivalent to arrayless JSON), with two special placeholders
for values: @config
and @runtime
. @config
means a
value that shall be filled from manila config, and @runtime
means a value that’s filled at runtime with dynamic data.
As an example, we show the library’s defaults in JSON format (also valid Python literal):
{ "EXPORT": { "Export_Id": "@runtime", "Path": "@runtime", "FSAL": { "Name": "@config" }, "Pseudo": "@runtime", "SecType": "sys", "Tag": "@runtime", "CLIENT": { "Clients": "@runtime", "Access_Type": "RW" }, "Squash": "None" } }
The Ganesha Library takes these values from
manila/share/drivers/ganesha/conf/00-base-export-template.conf
where the same data is stored in Ganesha conf format (also supplied with comments).
For customization, the driver has to extend the _default_config_hook
method as follows:
ganesha_utils.patch
methodWith respect to loading export blocks, that can be done through the
utility method _load_conf_dir
.
Following issues concern only users of ganesha.GaneshaNASHelper class that works with NFS-Ganesha v2.1 to v2.3.
<ganesha-server>:/share-<share-id>
. However,
this is incomplete information, because it pertains only to NFSv3
access, which is partially broken. NFSv4 mounts work well but the
actual NFSv4 export paths differ from the above. In detail:<ganesha-server>:/share-<share-id>--<access-id>
,
where <access-id>
ranges over the ID-s of access
rules of the share (and the export with <access-id>
is accessible according to the access rule of that ID).share-<share-id>--<access-id>
subdirectories.Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.