ZFS (on Linux) Driver

Manila ZFSonLinux share driver uses ZFS filesystem for exporting NFS shares. Written and tested using Linux version of ZFS.

Requirements

• ‘NFS’ daemon that can be handled via “exportfs” app.

• ‘ZFS’ filesystem packages, either Kernel or FUSE versions.

• ZFS zpools that are going to be used by Manila should exist and be configured as desired. Manila will not change zpool configuration.

• For remote ZFS hosts according to manila-share service host SSH should be installed.

• For ZFS hosts that support replication:

  • SSH access for each other should be passwordless.

  • Service IP addresses should be available by ZFS hosts for each other.

Supported Operations

The following operations are supported:

• Create NFS Share

• Delete NFS Share

• Manage NFS Share

• Unmanage NFS Share

• Allow NFS Share access

  • Only IP access type is supported for NFS

  • Both access levels are supported - ‘RW’ and ‘RO’

• Deny NFS Share access

• Create snapshot

• Delete snapshot

• Manage snapshot

• Unmanage snapshot

• Create share from snapshot

• Extend share

• Shrink share

• Replication (experimental):

  • Create/update/delete/promote replica operations are supported

• Share migration (experimental)

Possibilities

• Any amount of ZFS zpools can be used by share driver.

• Allowed to configure default options for ZFS datasets that are used for share creation.

• Any amount of nested datasets is allowed to be used.

• All share replicas are read-only, only active one is RW.

• All share replicas are synchronized periodically, not continuously. So, status ‘in_sync’ means latest sync was successful. Time range between syncs equals to value of config global opt ‘replica_state_update_interval’.

• Driver is able to use qualified extra spec ‘zfsonlinux:compression’. It can contain any value that is supported by used ZFS app. But if it is disabled via config option with value ‘compression=off’, then it will not be used.

Restrictions

The ZFSonLinux share driver has the following restrictions:

• Only IP access type is supported for NFS.

• Only FLAT network is supported.

• ‘Promote share replica’ operation will switch roles of current ‘secondary’ replica and ‘active’. It does not make more than one active replica available.

• ‘SaMBa’ based sharing is not yet implemented.

• ‘Thick provisioning’ is not yet implemented.

Known problems

• ‘Promote share replica’ operation will make ZFS filesystem that became secondary as RO only on NFS level. On ZFS level system will stay mounted as was - RW.

Backend Configuration

The following parameters need to be configured in the manila configuration file for the ZFSonLinux driver:

• share_driver = manila.share.drivers.zfsonlinux.driver.ZFSonLinuxShareDriver

• driver_handles_share_servers = False

• replication_domain = custom_str_value_as_domain_name

  • if empty, then replication will be disabled

  • if set then will be able to be used as replication peer for other backend with same value.

• zfs_share_export_ip = <user_facing IP address of ZFS host>

• zfs_service_ip = <IP address of service network interface of ZFS host>

• zfs_zpool_list = zpoolname1,zpoolname2/nested_dataset_for_zpool2

  • can be one or more zpools

  • can contain nested datasets

• zfs_dataset_creation_options = <list of ZFS dataset options>

  • readonly,quota,sharenfs and sharesmb options will be ignored

• zfs_dataset_name_prefix = <prefix>

  • Prefix to be used in each dataset name.

• zfs_dataset_snapshot_name_prefix = <prefix>

  • Prefix to be used in each dataset snapshot name.

• zfs_use_ssh = <boolean_value>

  • set ‘False’ if ZFS located on the same host as ‘manila-share’ service

  • set ‘True’ if ‘manila-share’ service should use SSH for ZFS configuration

• zfs_ssh_username = <ssh_username>

  • required for replication operations

  • required for SSH’ing to ZFS host if ‘zfs_use_ssh’ is set to ‘True’

• zfs_ssh_user_password = <ssh_user_password>

  • password for ‘zfs_ssh_username’ of ZFS host.

  • used only if ‘zfs_use_ssh’ is set to ‘True’

• zfs_ssh_private_key_path = <path_to_private_ssh_key>

  • used only if ‘zfs_use_ssh’ is set to ‘True’

• zfs_share_helpers = NFS=manila.share.drivers.zfsonlinux.utils.NFSviaZFSHelper

  • Approach for setting up helpers is similar to various other share driver

  • At least one helper should be used.

• zfs_replica_snapshot_prefix = <prefix>

  • Prefix to be used in dataset snapshot names that are created by ‘update replica’ operation.

• zfs_migration_snapshot_prefix = <prefix>

  • Prefix to be used in dataset snapshot names that are created for ‘migration’ operation.

Restart of manila-share service is needed for the configuration changes to take effect.

The manila.share.drivers.zfsonlinux.driver Module

Module with ZFSonLinux share driver that utilizes ZFS filesystem resources and exports them as shares.

class ZFSonLinuxShareDriver(*args, **kwargs)

Bases: manila.share.drivers.zfsonlinux.utils.ExecuteMixin, manila.share.driver.ShareDriver

create_replica(context, *args, **kwargs)

create_replicated_snapshot(context, *args, **kwargs)

create_share(context, *args, **kwargs)

create_share_from_snapshot(context, *args, **kwargs)

create_snapshot(context, *args, **kwargs)

delete_replica(context, *args, **kwargs)

delete_replicated_snapshot(context, *args, **kwargs)

delete_share(context, *args, **kwargs)

delete_snapshot(context, *args, **kwargs)

do_setup(context)

Perform basic setup and checks.

ensure_share(context, *args, **kwargs)

extend_share(context, *args, **kwargs)

get_network_allocations_number()

ZFS does not handle networking. Return 0.

get_pool(share)

Return pool name where the share resides on.

Parameters

share – The share hosted by the driver.

manage_existing(share, driver_options)

Manage existing ZFS dataset as manila share.

ZFSonLinux driver accepts only one driver_option ‘size’. If an administrator provides this option, then such quota will be set to dataset and used as share size. Otherwise, driver will set quota equal to nearest bigger rounded integer of usage size. Driver does not expect mountpoint to be changed (should be equal to default that is “/%(dataset_name)s”).

Parameters

• share – share data

• driver_options – Empty dict or dict with ‘size’ option.

Returns

dict with share size and its export locations.

manage_existing_snapshot(snapshot_instance, driver_options)

Manage existing share snapshot with manila.

Parameters

• snapshot_instance – SnapshotInstance data

• driver_options – expects only one optional key ‘size’.

Returns

dict with share snapshot instance fields for update, example:

{

‘size’: 1, ‘provider_location’: ‘path/to/some/dataset@some_snapshot_tag’,

}

migration_cancel(context, *args, **kwargs)

migration_check_compatibility(context, *args, **kwargs)

migration_complete(context, *args, **kwargs)

migration_continue(context, *args, **kwargs)

migration_start(context, *args, **kwargs)

promote_replica(context, *args, **kwargs)

shrink_share(context, *args, **kwargs)

unmanage(share)

Removes the specified share from Manila management.

unmanage_snapshot(snapshot_instance)

Unmanage dataset snapshot.

update_access(context, *args, **kwargs)

update_replica_state(context, *args, **kwargs)

update_replicated_snapshot(context, *args, **kwargs)

ensure_share_server_not_provided(f)

get_backend_configuration(backend_name)

The manila.share.drivers.zfsonlinux.utils Module

Module for storing ZFSonLinux driver utility stuff such as:

• Common ZFS code

• Share helpers

class ExecuteMixin

Bases: manila.share.driver.ExecuteMixin

execute(*cmd, **kwargs)

Common interface for running shell commands.

execute_with_retry(*cmd, **kwargs)

Retry wrapper over common shell interface.

get_zfs_option(dataset_name, option_name, **kwargs)

Returns value of requested zfs dataset option.

get_zpool_option(zpool_name, option_name, **kwargs)

Returns value of requested zpool option.

init_execute_mixin(*args, **kwargs)

Init method for mixin called in the end of driver’s __init__().

parse_zfs_answer(string)

Returns list of dicts with data returned by ZFS shell commands.

zfs(*cmd, **kwargs)

ZFS shell commands executor.

zfs_with_retry(*cmd, **kwargs)

ZFS shell commands executor.

class NASHelperBase(configuration)

Bases: object

Base class for share helpers of ‘ZFS on Linux’ driver.

abstract create_exports(dataset_name, executor)

Creates share exports.

abstract get_exports(dataset_name, service, executor)

Gets/reads share exports.

abstract remove_exports(dataset_name, executor)

Removes share exports.

abstract update_access(dataset_name, access_rules, add_rules, delete_rules, executor)

Update access rules for specified ZFS dataset.

abstract verify_setup()

Performs checks for required stuff.

class NFSviaZFSHelper(configuration)

Bases: manila.share.drivers.zfsonlinux.utils.ExecuteMixin, manila.share.drivers.zfsonlinux.utils.NASHelperBase

Helper class for handling ZFS datasets as NFS shares.

Kernel and Fuse versions of ZFS have different syntax for setting up access rules, and this Helper designed to satisfy both making autodetection.

create_exports(dataset_name, executor=None)

Creates NFS share exports for given ZFS dataset.

get_exports(dataset_name, executor=None)

Gets/reads NFS share export for given ZFS dataset.

property is_kernel_version

Says whether Kernel version of ZFS is used or not.

remove_exports(*args, **kwargs)

update_access(*args, **kwargs)

verify_setup()

Performs checks for required stuff.

get_remote_shell_executor(ip, port, conn_timeout, login=None, password=None, privatekey=None, max_size=10)

zfs_dataset_synchronized(f)