Ganesha Library¶
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.
Supported operations¶
- Allow NFS Share access
- Only IP access type is supported.
- Deny NFS Share access
Requirements¶
NFS-Ganesha 2.1 or newer.
NFS-Ganesha configuration¶
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:
- ganesha_config_dir = toplevel directory for Ganesha configuration,
defaults to /etc/ganesha
- ganesha_config_path = location of the Ganesha config file, defaults
to ganesha.conf in ganesha_config_dir
- ganesha_export_dir = directory where Manila generated config bits are
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
Using Ganesha Library in drivers¶
A driver that wants to use the Ganesha Library has to inherit
from driver.GaneshaMixin
.
The driver has to contain a subclass of ganesha.GaneshaNASHelper
,
instantiate it along with the driver instance and delegate
allow_access
and deny_access
methods to it (when appropriate,
ie. when access_proto
is NFS).
In the following we explain what has to be implemented by the
ganesha.GaneshaNASHelper
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": "GLUSTER"}
). Further content of it is
optional and FSAL specific.
Customizing Ganesha exports¶
As noted, the Ganesha Library provides sane general defaults.
However, the driver is allowed to:
- customize defaults
- allow users to customize exports
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:
- take the result of the super method (a dict representing an export block template)
- set up another export block dict that include your custom values,
either by
- using a predefined export block dict stored in code
- loading a predefined export block from the Manila source tree
- loading an export block from an user exposed location (to allow user configuration)
- merge the two export block dict using the
ganesha_utils.patch
method - return the result
With respect to loading export blocks, that can be done through the
utility method _load_conf_dir
.
Known Restrictions¶
- The library does not support network segmented multi-tenancy model but instead works over a flat network, where the tenants share a network.