ZFS (on Linux) driver

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

Requirements

• NFS daemon that can be handled through exportfs app.

• ZFS file system 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 shared filesystems and operations

The driver supports NFS shares.

The following operations are supported:

• Create a share.

• Delete a share.

• Allow share access.

  • Only IP access type is supported.

  • Both access levels are supported - RW and RO.

• Deny share access.

• Bring an existing ZFSOnLinux share under the shared file system service (Managing a share)

• Remove a ZFSOnLinux share from the shared file system service without deleting it (Unmanaging a share)

• Create a snapshot.

• Delete a snapshot.

• Bring an existing ZFSOnLinux snapshot under the shared file system service (Managing a snapshot)

• Remove a ZFSOnLinux snapshot from the shared file system service without deleting it (Unmanaging a snapshot)

• Create a share from snapshot.

• Extend a share.

• Shrink a share.

• Share replication (experimental):

  • Create, update, delete, and promote replica operations are supported.

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 read-write.

• All share replicas are synchronized periodically, not continuously. Status in_sync means latest sync was successful. Time range between syncs equals to the value of the replica_state_update_interval configuration global option.

• Driver can use qualified extra spec zfsonlinux:compression. It can contain any value that ZFS app supports. But if it is disabled through the configuration option with the 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.

• The below items are not yet implemented:

  • SaMBa based sharing.

  • Thick provisioning capability.

Known problems

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

Back-end configuration

The following parameters need to be configured in the manila configuration file for back-ends that use 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 back ends with the 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 drivers.

  • 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.

Driver options

Description of ZFS share driver configuration options

Configuration option = Default value	Description
[DEFAULT]
zfs_dataset_creation_options = None	(List) Define here list of options that should be applied for each dataset creation if needed. Example: compression=gzip,dedup=off. Note that, for secondary replicas option ‘readonly’ will be set to ‘on’ and for active replicas to ‘off’ in any way. Also, ‘quota’ will be equal to share size. Optional.
zfs_dataset_name_prefix = manila_share_	(String) Prefix to be used in each dataset name. Optional.
zfs_dataset_snapshot_name_prefix = manila_share_snapshot_	(String) Prefix to be used in each dataset snapshot name. Optional.
zfs_migration_snapshot_prefix = tmp_snapshot_for_share_migration_	(String) Set snapshot prefix for usage in ZFS migration. Required.
zfs_replica_snapshot_prefix = tmp_snapshot_for_replication_	(String) Set snapshot prefix for usage in ZFS replication. Required.
zfs_service_ip = None	(String) IP to be added to admin-facing export location. Required.
zfs_share_export_ip = None	(String) IP to be added to user-facing export location. Required.
zfs_share_helpers = NFS=manila.share.drivers.zfsonlinux.utils.NFSviaZFSHelper	(List) Specify list of share export helpers for ZFS storage. It should look like following: ‘FOO_protocol=foo.FooClass,BAR_protocol=bar.BarClass’. Required.
zfs_ssh_private_key_path = None	(String) Path to SSH private key that should be used for SSH’ing ZFS storage host. Not used for replication operations. Optional.
zfs_ssh_user_password = None	(String) Password for user that is used for SSH’ing ZFS storage host. Not used for replication operations. They require passwordless SSH access. Optional.
zfs_ssh_username = None	(String) SSH user that will be used in 2 cases: 1) By manila-share service in case it is located on different host than its ZFS storage. 2) By manila-share services with other ZFS backends that perform replication. It is expected that SSH’ing will be key-based, passwordless. This user should be passwordless sudoer. Optional.
zfs_use_ssh = False	(Boolean) Remote ZFS storage hostname that should be used for SSH’ing. Optional.
zfs_zpool_list = None	(List) Specify list of zpools that are allowed to be used by backend. Can contain nested datasets. Examples: Without nested dataset: ‘zpool_name’. With nested dataset: ‘zpool_name/nested_dataset_name’. Required.