API

Enumerations

class simplezfs.types.DatasetType(value)

Enumeration of dataset types that ZFS supports.

BOOKMARK = 'bookmark': Dataset is a bookmark

FILESET = 'fileset': Dataset is an ordinary fileset

SNAPSHOT = 'snapshot': Dataset is a snapshot

VOLUME = 'volume': Dataset is a ZVOL

static from_string(value)

Helper to convert a string to an instance.

Parameters: value (str) – The string to converts.
Return type: DatasetType
Returns: The enum value
Raises: ValueError – If the supplied value is not found in the enumeration.

class simplezfs.types.PEHelperMode(value)

Modes for chosing whether to use the PEHelper and how.

DO_NOT_USE = 0: Do not use the PEHelper

USE_IF_REQUIRED = 1: Use if ZFS indicates it is required

USE_PROACTIVE = 2: Use proactively for actions known to require it

class simplezfs.types.PropertySource(value)

Enumeration of the valid property sources in ZFS.

DEFAULT = 'default': Property is at default

INHERITED = 'inherited': Property was inerited

LOCAL = 'local': Property was defined on the dataset itself

NONE = 'none': Property is set on the dataset in question

RECEIVED = 'received': Property value is set due to a “zfs send/receive” operation.

TEMPORARY = 'temporary': Property is temporary

static from_string(value)

Helper to convert a string to an instance.

Parameters: value (Union[bytes, str]) – The string to convert.
Return type: PropertySource
Returns: The enum value.
Raises: ValueError – If the supplied value is not found in the enumeration.

class simplezfs.types.ZPoolHealth(value)

Pool health.

AVAIL = 'AVAIL': This one is used for spares

static from_string(value)

Helper to convert a string to an instance.

Parameters: value (str) – The string to convert.
Return type: ZPoolHealth
Returns: The enum value.
Raises: ValueError – If the supplied value is not found in the enumeration.

Types

class simplezfs.types.Dataset(name: str, full_path: str, pool: str, parent: Optional[str], type: simplezfs.types.DatasetType)

Container describing a single dataset.

static from_string(value)

Helper to convert a string to a Dataset.

Parameters: value (str) – The value to convert.
Raises: ValidationError – if the value can’t be converted.
Return type: Dataset
Returns: the dataset instance

full_path: str: Full path to and including the dataset itself

name: str: Name of the dataset (excluding the path)

parent: Optional[str]: Parent dataset, or None for the topmost dataset (pool)

pool: str: Pool name

type: simplezfs.types.DatasetType: Dataset type

class simplezfs.types.Property(key: str, value: str, source: simplezfs.types.PropertySource = PropertySource.NONE, namespace: Optional[str] = None)

Container for a single ZFS property.

key: str: Key or name of the property (excluding namespace for non-native properties)

namespace: Optional[str]: Namespace name of the property, None for native properties

source: simplezfs.types.PropertySource: Source of the property value

value: str: Value of the property

Interfaces

ZFS

simplezfs.zfs.get_zfs(api='cli', metadata_namespace=None, **kwargs)

Returns an instance of the desired ZFS API. Default is cli.

Using this function is an alternative to instantiating one of the implementations yourself.

The parameters metadata_namespace and all of the kwargs are passed to the implementations constructor.

Example:

>>> from zfs import get_zfs, ZFS
>>> type(get_zfs('cli'))
<class 'zfs.zfs_cli.ZFSCli'>
>>> type(get_zfs('native'))
<class 'zfs.zfs_native.ZFSNative'>
>>> isinstance(get_zfs(), ZFS)
True

Parameters

api (str) – API to use, either cli for zfs(8) or native for the libzfs_core api.
metadata_namespace (Optional[str]) – Default namespace.
kwargs – Extra parameters to pass to the implementations constructor.

Return type

ZFS

Returns

An API instance.

Raises

NotImplementedError – If an unknown API was requested.

class simplezfs.zfs.ZFS(*, metadata_namespace=None, pe_helper=None, pe_helper_mode=PEHelperMode.DO_NOT_USE, **kwargs)

ZFS interface class. This API generally covers only the zfs(8) tool, for zpool(8) please see ZPool.

ZFS implementation

There are two ways how the API actually communicates with the ZFS filesystem:

Using the CLI tools (ZFSCli)
Using the native API (ZFSNative)

You can select the API by either creating an instance of one of them or using get_zfs().

Properties and Metadata

The functions set_property(), get_property() and get_properties() wrap the ZFS get/set functionality. To support so-called user properties, which are called metadata in this API, a default namespace can be stored using metadata_namespace when instantiating the interface or by calling set_metadata_namespace() at any time.

Note: Not setting a metadata namespace means that one can’t set or get metadata properties, unless the overwrite parameter for the get/set functions is used.

The parameter use_pe_helper is used to control whether the pe_helper will be used when performing actions that require elevated permissions. It can be changed at anytime using the use_pe_helper property.

Changed in version 0.0.3: use_pe_helper became pe_helper_mode

Parameters

metadata_namespace (Optional[str]) – Default namespace
pe_helper (Optional[PEHelperBase]) – Privilege escalation (PE) helper to use for actions that require elevated privileges (root).
pe_helper_mode (PEHelperMode) – How and when to use the PEHelper. Defaults to not using it at all.
kwargs – Extra arguments, ignored

create_bookmark(snapshot, name)

Create a new bookmark from an existing snapshot.

Parameters

snapshot (str) – The snapshot to attach a bookmark to.
name (str) – Name of the bookmark (the part after the #)

Return type

Dataset

Returns

Info about the newly created dataset.

Raises

ValidationError – If validating the parameters failed.
DatasetNotFound – If the snapshot can’t be found.

create_dataset(name, *, dataset_type=DatasetType.FILESET, properties=None, metadata_properties=None, sparse=False, size=None, recursive=False)

Create a new dataset. The dataset_type parameter contains the type of dataset to create. This is a generic function to create datasets, you may want to take a look at the more specific functions (that essentially call this one) for convenience:

create_fileset()
create_snapshot()
create_volume()

Properties specified with this call will be included in the create operation and are thus atomic. An exception applies for filesets with mountpoints that are neither none nor legacy on Linux.

Note

Bookmarks can’t be created this way, use create_bookmark() for that.

Warning

On Linux, only root is allowed to manipulate the namespace (aka mount). Refer to The mount problem in the documentation.

Parameters

name (str) – The name of the new dataset. This includes the full path, e.g. tank/data/newdataset.
dataset_type (DatasetType) – Indicates the type of the dataset to be created.
properties (Optional[Dict[str, str]]) – A dict containing the properties for this new dataset. These are the native properties.
metadata_properties (Optional[Dict[str, str]]) – The metadata properties to set. To use a different namespace than the default (or when no default is set), use the namespace:key format for the dict keys.
sparse (bool) – For volumes, specifies whether a sparse (thin provisioned) or normal (thick provisioned) volume should be created.
size (Optional[int]) – For volumes, specifies the size in bytes.
recursive (bool) – Recursively create the parent fileset. Refer to the ZFS documentation about the -p parameter for zfs create. This does not apply to types other than volumes or filesets.

Raises

ValidationError – If validating the parameters failed.
DatasetNotFound – If the dataset (snapshot) or parent dataset (filesets and volumes with recursive set to False) can’t be found.

Return type

Dataset

create_fileset(name, *, mountpoint=None, properties=None, metadata_properties=None, recursive=True)

Create a new fileset. For convenience, a mountpoint parameter can be given. If not None, it will overwrite any mountpoint value in the properties dict.

Warning

This action requires the pe_helper on Linux when not running as root.

Note

If the function raises a PermissionError or PEHelperException, the fileset may have been created, but is missing its mountpoint property (along with it not being mounted) or other properties to which the user has no permission to change (not in zfs allow).

Parameters

name (str) – Name of the new fileset (complete path in the ZFS hierarchy).
properties (Optional[Dict[str, str]]) – Dict of native properties to set.
metadata_properties (Optional[Dict[str, str]]) – Dict of native properties to set. For namespaces other than the default (or when no default has been set, format the key using namespace:key.
recursive (bool) – Recursively create the parent fileset. Refer to the ZFS documentation about the -p parameter for zfs create.

Ppram mountpoint

Convenience parameter for setting/overwriting the moutpoint property

Return type

Dataset

Returns

Info about the newly created dataset.

Raises

ValidationError – If validating the parameters failed.
DatasetNotFound – If the parent dataset can’t be found and recursive is False.

create_snapshot(dataset, name, *, properties=None, metadata_properties=None)

Create a new snapshot from an existing dataset.

Warning

This action requires the pe_helper on Linux when not running as root.

Parameters

dataset (str) – The dataset to snapshot.
name (str) – Name of the snapshot (the part after the @)
properties (Optional[Dict[str, str]]) – Dict of native properties to set.
metadata_properties (Optional[Dict[str, str]]) – Dict of native properties to set. For namespaces other than the default (or when no default has been set, format the key using namespace:key.

Return type

Dataset

Returns

Info about the newly created dataset.

Raises

ValidationError – If validating the parameters failed.
DatasetNotFound – If the dataset can’t be found.

create_volume(name, *, size, sparse=False, blocksize=None, properties=None, metadata_properties=None, recursive=False)

Create a new volume of the given size (in bytes). If sparse is True, a sparse volume (also known as thin provisioned) will be created. If blocksize is given, it overwrites the blocksize property.

Note

Please read the note in create_fileset() for permission handling for filesystems. Generally, if the user does not have permission to set certain properties, the dataset may or may not have been created but is missing the properties. It is up to the user of the library to clean up after catching a PermissionError.

Parameters

name (str) – Name of the new volume (complete path in the ZFS hierarchy).
size (int) – The size (in bytes) for the new volume.
sparse (bool) – Whether to create a sparse volume. Requires size to be set.
blocksize (Optional[int]) – If set, overwrites the blocksize property. Provided for convenience.
properties (Optional[Dict[str, str]]) – Dict of native properties to set.
metadata_properties (Optional[Dict[str, str]]) – Dict of native properties to set. For namespaces other than the default (or when no default has been set, format the key using namespace:key.
recursive (bool) – Recursively create the parent fileset. Refer to the ZFS documentation about the -p parameter for zfs create.

Return type

Dataset

Returns

Info about the newly created dataset.

Raises

ValidationError – If validating the parameters failed.
DatasetNotFound – If the parent dataset can’t be found and recursive is False.

dataset_exists(name)

Checks is a dataset exists. This is done by querying for its type property.

Parameters: name (str) – Name of the dataset to check for.
Return type: bool
Returns: Whether the dataset exists.

destroy_dataset(dataset, *, recursive=False, force_umount=False)

Destroy a dataset. This function tries to remove a dataset, optionally removing all children recursively if recursive is True. This function works on all types of datasets, fileset, volume, snapshot and bookmark.

This function can’t be used to destroy pools, please use ZPool instead.

Example:

>>> zfs = ZFSCli()
>>> zfs.destroy_dataset('pool/system/root@pre-distupgrade')

Note

This is a destructive process that can’t be undone.

Parameters

dataset (str) – Name of the dataset to remove.
recursive (bool) – Whether to recursively delete child datasets such as snapshots.
force_umount (bool) – Forces umounting before destroying. Refer to ZFS(8) zfs destroy parameter -f.

Raises

ValidationError – If validating the parameters failed.
DatasetNotFound – If the dataset can’t be found.

Return type

None

get_dataset_info(name)

Returns basic information about a dataset. To retrieve its properties, see get_property() and get_properties().

Parameters

name (str) – The name of the dataset in question.

Return type

Dataset

Returns

The dataset info.

Raises

DatasetNotFound – If the dataset does not exist.
ValidationError – If the name was invalid.

get_properties(dataset, *, include_metadata=False)

Gets all properties from the dataset. By default, only native properties are returned. To include metadata properties, set include_metadata to True. In this mode, all properties are included, regardless of metadata_namespace, it is up to the user to filter the metadata.

Parameters

dataset (str) – Name of the dataset to get properties from. Expects the full path beginning with the pool name.
include_metadata (bool) – If True, returns metadata (user) properties in addition to native properties.

Raises

DatasetNotFound – If the dataset does not exist.
ValidationError – If validating the parameters failed.

Return type

List[Property]

get_property(dataset, key, *, metadata=False, overwrite_metadata_namespace=None)

Gets a specific property named key from the dataset. By default, only native properties are returned. This behaviour can be changed by setting metadata to True, which uses the default metadata_namespace to select the namespace. The namespace can be overwritten using overwrite_metadata_namespace for the duration of the method invocaton.

Parameters

dataset (str) – Name of the dataset to get the property. Expects the full path beginning with the pool name.
key (str) – Name of the property to set. For non-native properties, set metadata to True and overwrite the default namespace using overwrite_metadata_namespace if required.
metadata (bool) – If True, prepend the namespace to set a user (non-native) property.
overwrite_metadata_namespace (Optional[str]) – Overwrite the default namespace for user (non-native) properties.

Raises

DatasetNotFound – If the dataset does not exist.
ValidationError – If validating the parameters failed.

Return type

Property

list_datasets(*, parent=None)

Lists all datasets known to the system. If parent is set to a pool or dataset name (or a Dataset), lists all the children of that dataset.

Parameters: parent (Union[str, Dataset, None]) – If set, list all child datasets.
Return type: List[Dataset]
Returns: The list of datasets.

property metadata_namespace: Optional[str]

Returns the metadata namespace, which may be None if not set.

Return type: Optional[str]

property pe_helper: Optional[simplezfs.pe_helper.PEHelperBase]

Returns or changes the privilege escalation (PE) helper. A value of None means none set.

Return type: Optional[PEHelperBase]

property pe_helper_mode: simplezfs.types.PEHelperMode

Returns or sets whether the privilege escalation (PE) helper should be used and when. If the helper has not been set, this property evaluates to False.

New in version 0.0.3.

Return type: PEHelperMode

set_mountpoint(fileset, mountpoint, *, pe_helper_mode=None)

Sets or changes the mountpoint property of a fileset. While this can be achieved using the generic function set_property(), it allows for using the privilege escalation (PE) helper if so desired.

The argument pe_helper_mode can overwrite the property of the same name. If the argument is None, the properties value will be assumed. In any case, the function attempts to set the property on its own first. If that fails, it evaluates if the PE helper should be used, and will error out if it should be used but has not been set. If the helper fails, a PEHelperException is raised.

Parameters

fileset (str) – The fileset to modify.
mountpoint (str) – The new value for the mountpoint property.
pe_helper_mode (Optional[PEHelperMode]) – Overwrite the default for using the privilege escalation (PE) helper for this task. None (default) uses the default setting. If the helper is not set, it is not used.

Raises

DatasetNotFound – if the fileset could not be found.
ValidationError – if validating the parameters failed.

Return type

None

set_property(dataset, key, value, *, metadata=False, overwrite_metadata_namespace=None)

Sets the value of the native property key. By default, only native properties can be set. If metadata is set to True, the default metadata namespace is prepended or the one in overwrite_metadata_namespace is used if set to a valid string.

Note

Use set_mountpoint() to change the mountpoint property if your setup requires the use of elevated permissions (such as Linux).

Example:

>>> z = ZFSCli(namespace='foo')
>>> z.set_property('tank/test', 'testprop', 'testval', metadata=True, overwrite_metadata_namespace='bar')
>>> z.get_property('tank/test', 'testprop')
Exception
>>> z.get_property('tank/test', 'testprop', metadata=True)
Exception
>>> z.get_property('tank/test', 'testprop', metadata=True, overwrite_metadata_namespace='bar')
Property(key='testprop', val='testval', source='local', namespace='bar')

Parameters

dataset (str) – Name of the dataset to set the property. Expects the full path beginning with the pool name.
key (str) – Name of the property to set. For non-native properties, set metadata to True and overwrite the default namespace using overwrite_metadata_namespace if required.
value (str) – The new value to set.
metadata (bool) – If True, prepend the namespace to set a user (non-native) property.
overwrite_metadata_namespace (Optional[str]) – Overwrite the default metadata namespace for user (non-native) properties

Raises

DatasetNotFound – If the dataset could not be found.
ValidationError – If validating the parameters failed.

Return type

None

property use_pe_helper: bool

Returns or sets whether the privilege escalation (PE) helper should be used. If the helper has not been set, reading the property returns False.

Deprecated since version 0.0.3: Use pe_helper_mode() instead. Returns whether the helper mode is not set to PEHelperMode.DO_NOT_USE if the helper is set. If set to False, sets the mode to DO_NOT_USE, True sets it to USE_IF_REQUIRED unless it is already set to USE_PROACTIVE, in which case it will do nothing.

This property will be removed in 0.0.4!

Return type: bool

ZPool

simplezfs.zpool.get_zpool(api='cli', metadata_namespace=None, **kwargs)

Returns an instance of the desired ZPool API. Default is cli.

Using this function is an alternative to instantiating one of the implementations yourself and is the recommended way to get an instance.

Example:

>>> from zfs import get_zpool, ZPool
>>> type(get_zpool('cli'))
<class 'zfs.zpool_cli.ZPoolCli'>
>>> type(get_zpool('native'))
<class 'zfs.zpool_native.ZPoolNative'>
>>> isinstance(get_zpool(), ZPool)
True

Return type: ZPool

class simplezfs.zpool.ZPool(*, metadata_namespace=None, pe_helper=None, pe_helper_mode=PEHelperMode.DO_NOT_USE, **kwargs)

ZPool interface class. This API generally covers only the zpool(8) tool, for zfs(8) please see class ZFS.

ZFS implementation

There are two ways how the API actually communicates with the ZFS filesystem:

Using the CLI tools
Using the native API

When creating an instance of this class, select one or the other as the api argument.

Properties and Metadata

Please see the documentation for ZFS for native and metadata properties.

Parameters

metadata_namespace (Optional[str]) – Default namespace
pe_helper (Optional[PEHelperBase]) – Privilege escalation (PE) helper to use for actions that require elevated privileges (root).
pe_helper_mode (PEHelperMode) – How and when to use the PEHelper. Defaults to not using it at all.
kwargs – Extra arguments, ignored

property metadata_namespace: Optional[str]

Returns the metadata namespace, which may be None if not set.

Return type: Optional[str]

property pe_helper: Optional[simplezfs.pe_helper.PEHelperBase]

Returns the pe_helper, which may be None if not set.

Return type: Optional[PEHelperBase]

property pe_helper_mode: simplezfs.types.PEHelperMode

Returns whether the privilege escalation (PE) helper should be used and when. If the helper has not been set, this property evaluates to False.

Return type: PEHelperMode

Implementations

class simplezfs.zfs_cli.ZFSCli(*, metadata_namespace=None, pe_helper=None, pe_helper_mode=PEHelperMode.DO_NOT_USE, zfs_exe=None, **kwargs)

ZFS interface implementation using the zfs(8) command line utility. For documentation, please see the interface ZFS. It is recommended to use get_zfs() to obtain an instance using cli as api.

If zfs_exe is supplied, it is assumed that it points to the path of the zfs(8) executable.

property executable: str

Returns the zfs executable that was found by find_executable.

Return type: str

find_executable(path=None)

Tries to find the executable zfs(8). If path points to an executable, it is used instead of relying on the PATH to find it. It does not fall back to searching in $PATH of path does not point to an executable. An exception is raised if no executable could be found.

Parameters: path (Optional[str]) – Path to the executable, used blindly if supplied.
Raises: OSError – If the executable could not be found.
Return type: None

get_dataset_info(name)

Returns basic information about a dataset. To retrieve its properties, see get_property() and get_properties().

Parameters

name (str) – The name of the dataset in question.

Return type

Dataset

Returns

The dataset info.

Raises

DatasetNotFound – If the dataset does not exist.
ValidationError – If the name was invalid.

handle_command_error(proc, dataset=None)

Handles errors that occured while running a command.

Parameters

proc (CompletedProcess) – The result of subprocess.run
dataset (Optional[str]) – If the error was caused by working with a dataset, specify it to enhance the error message.

Todo

propper exception!

Raises

DatasetNotFound – If zfs could not find the dataset it was requested to work with.
PropertyNotFound – If the could not find the property it was asked to work with.
PermissionError – If zfs denied the operation, or if only root is allowed to carry it out.
Exception – tmp

Return type

NoReturn

static is_zvol(name)

Resolves the given name in the dev filesystem. If it is found beneath /dev/zvol, True is returned.

Parameters: name (str) – The name of the suspected volume
Return type: bool
Returns: Whether the name represents a volume rather than a fileset.
Raises: ValidationError – If validation fails.

list_datasets(*, parent=None)

Todo: ability to limit to a pool (path validator discards pool-only arguments)
Todo: find a way to tell the user to use ZPool for pools if only a pool is given
Return type: List[Dataset]

class simplezfs.zfs_native.ZFSNative(*, metadata_namespace=None, pe_helper=None, use_pe_helper=False, **kwargs)

ZFS interface implementation using the libzfs_core python bindings. For documentation, please see the interface ZFS. It is recommended to use get_zfs() to obtain an instance, using native as api.

get_properties(dataset, *, include_metadata=False)

Gets all properties from the dataset. By default, only native properties are returned. To include metadata properties, set include_metadata to True. In this mode, all properties are included, regardless of metadata_namespace, it is up to the user to filter the metadata.

Parameters

dataset (str) – Name of the dataset to get properties from. Expects the full path beginning with the pool name.
include_metadata (bool) – If True, returns metadata (user) properties in addition to native properties.

Raises

DatasetNotFound – If the dataset does not exist.
ValidationError – If validating the parameters failed.

Return type

List[Property]

get_property(dataset, key, *, metadata=False, overwrite_metadata_namespace=None)

Gets a specific property named key from the dataset. By default, only native properties are returned. This behaviour can be changed by setting metadata to True, which uses the default metadata_namespace to select the namespace. The namespace can be overwritten using overwrite_metadata_namespace for the duration of the method invocaton.

Parameters

dataset (str) – Name of the dataset to get the property. Expects the full path beginning with the pool name.
key (str) – Name of the property to set. For non-native properties, set metadata to True and overwrite the default namespace using overwrite_metadata_namespace if required.
metadata (bool) – If True, prepend the namespace to set a user (non-native) property.
overwrite_metadata_namespace (Optional[str]) – Overwrite the default namespace for user (non-native) properties.

Raises

DatasetNotFound – If the dataset does not exist.
ValidationError – If validating the parameters failed.

Return type

Property

set_property(dataset, key, value, *, metadata=False, overwrite_metadata_namespace=None)

Sets the value of the native property key. By default, only native properties can be set. If metadata is set to True, the default metadata namespace is prepended or the one in overwrite_metadata_namespace is used if set to a valid string.

Note

Use set_mountpoint() to change the mountpoint property if your setup requires the use of elevated permissions (such as Linux).

Example:

>>> z = ZFSCli(namespace='foo')
>>> z.set_property('tank/test', 'testprop', 'testval', metadata=True, overwrite_metadata_namespace='bar')
>>> z.get_property('tank/test', 'testprop')
Exception
>>> z.get_property('tank/test', 'testprop', metadata=True)
Exception
>>> z.get_property('tank/test', 'testprop', metadata=True, overwrite_metadata_namespace='bar')
Property(key='testprop', val='testval', source='local', namespace='bar')

Parameters

dataset (str) – Name of the dataset to set the property. Expects the full path beginning with the pool name.
key (str) – Name of the property to set. For non-native properties, set metadata to True and overwrite the default namespace using overwrite_metadata_namespace if required.
value (str) – The new value to set.
metadata (bool) – If True, prepend the namespace to set a user (non-native) property.
overwrite_metadata_namespace (Optional[str]) – Overwrite the default metadata namespace for user (non-native) properties

Raises

DatasetNotFound – If the dataset could not be found.
ValidationError – If validating the parameters failed.

Return type

None

class simplezfs.zpool_cli.ZPoolCli(*, metadata_namespace=None, pe_helper=None, pe_helper_mode=PEHelperMode.DO_NOT_USE, zpool_exe=None, **kwargs)

ZPOOL interface implementation using the zpool(8) command line utility. For documentation, please see the interface ZPool. It is recommended to use get_zpool() to obtain an instance using cli as api.

If zpool_exe is supplied, it is assumed that it points to the path to the zpool(8) executable.

property executable: str

Returns the zpool executable that was found by find_executable.

Return type: str

find_executable(path=None)

Tries to find the executable zpool. If path points to an executable, it is used instead of relying on the PATH to find it. It does not fall back to searching in PATH if path does not point to an exeuctable. An exception is raised if no executable could be found.

Parameters: path (Optional[str]) – Path to the executable, used blindly if supplied.
Raises: OSError – If the executable could not be found.
Return type: None

parse_pool_structure(zpool_list_output)

Parses the output of zpool list -vPHp and emits a list of pool structures.

Return type: Dict

class simplezfs.zpool_native.ZPoolNative(*, metadata_namespace=None, pe_helper=None, use_pe_helper=False, **kwargs): ZPool interface implementation using the libzfs_core python bindings. For documentation, please see the interface ZPool. It is recommended to use get_zpool() to obtain an instance, using native as api.

Privilege escalation

class simplezfs.pe_helper.PEHelperBase

Base class for Privilege Escalation (PE) helper implementations.

zfs_destroy_dataset(dataset, recursive, force_umount)

Destroy the given dataset.

Raises

ValidationError – If parameters do not validate.
PEHelperException – If errors are encountered when running the helper.

zfs_mount(fileset)

Tries to mount fileset to the location its mountpoint property points to. It does not check if the fileset has a valid mountpoint property.

Raises

ValidationError – If parameters do not validate.
PEHelperException – If errors are encountered when running the helper.

Return type

None

zfs_set_mountpoint(fileset, mountpoint)

Sets the mountpoint property of the given fileset.

Raises

ValidationError – If parameters do not validate.
PEHelperException – If errors are encountered when running the helper.

Return type

None

zfs_umount(fileset)

Tries to umount fileset. It does not check if the fileset is mounted.

Raises

ValidationError – If parameters do not validate.
PEHelperException – If errors are encountered when running the helper.

Return type

None

class simplezfs.pe_helper.ExternalPEHelper(executable)

Implementation using an external script to safeguard the operations.

zfs_set_mountpoint(fileset, mountpoint)

Sets the mountpoint property of the given fileset.

Raises

ValidationError – If parameters do not validate.
PEHelperException – If errors are encountered when running the helper.

Return type

None

class simplezfs.pe_helper.SudoPEHelper

Implementation using sudo(8).

zfs_destroy_dataset(dataset, recursive, force_umount)

Destroy the given dataset.

Raises

ValidationError – If parameters do not validate.
PEHelperException – If errors are encountered when running the helper.

Return type

None

zfs_mount(fileset)

Tries to mount fileset to the location its mountpoint property points to. It does not check if the fileset has a valid mountpoint property.

Raises

ValidationError – If parameters do not validate.
PEHelperException – If errors are encountered when running the helper.

Return type

None

zfs_set_mountpoint(fileset, mountpoint)

Sets the mountpoint property of the given fileset.

Raises

ValidationError – If parameters do not validate.
PEHelperException – If errors are encountered when running the helper.

Return type

None

zfs_umount(fileset)

Tries to umount fileset. It does not check if the fileset is mounted.

Raises

ValidationError – If parameters do not validate.
PEHelperException – If errors are encountered when running the helper.

Return type

None

Validation functions

A set of validation functions exist to validate names and other data. All of them raise a simplezfs.exceptions.ValidationError as a result of a failed validation and return nothing if everything is okay.

simplezfs.validation.validate_dataset_name(name, *, strict=False)

Validates a dataset name. By default (strict set to False) a snapshot (name@snapshotname) or bookmark (name#bookmarkname) postfix are allowed. Otherwise, these names are rejected. To validate a complete path, see validate_dataset_path().

Example:

>>> from zfs.validation import validate_dataset_name
>>> validate_dataset_name('swap')
>>> validate_dataset_name('backup', strict=True)
>>> validate_dataset_name('backup@20190525', strict=True)
zfs.validation.ValidationError: snapshot or bookmark identifier are not allowed in strict mode
>>> validate_dataset_name('')
zfs.validation.ValidationError: name is too short
>>> validate_dataset_name('pool/system')
zfs.validation.ValidationError: name contains disallowed characters
>>> validate_dataset_name('a' * 1024)  # really long name
zfs.validation.ValidationError: length > 255

Parameters

name (str) – The name to validate
strict (bool) – Whether to allow (False) or disallow (True) snapshot and bookmark names.

Raises

ValidationError – Indicates validation failed

Return type

None

simplezfs.validation.validate_dataset_path(path)

Validates a path of datasets. While validate_dataset_name() validates only a single entry in a path to a dataset, this function validates the whole path beginning with the pool.

Raises: ValidationError – Indicates validation failed
Return type: None

simplezfs.validation.validate_native_property_name(name)

Validates the name of a native property. Length and syntax is checked.

Note: No check is performed to match the name against the actual names the target ZFS version supports.
Raises: ValidationError – Indicates that the validation failed.
Return type: None

simplezfs.validation.validate_metadata_property_name(name)

Validate the name of a metadata property (user property in ZFS manual).

Raises: ValidationError – Indicates that the validation failed.
Return type: None

simplezfs.validation.validate_pool_name(name)

Validates a pool name.

Raises: ValidationError – Indicates validation failed
Return type: None

simplezfs.validation.validate_property_value(value)

Validates the value of a property. This works for both native properties, where the driver will tell us if the value was good or not, as well metadata (or user) properties where the only limit is its length.

Parameters: value (str) – The value to validate.
Raises: ValidationError – Indicates that the validation failed.
Return type: None

Exceptions

exception simplezfs.exceptions.ZFSException

Base for the exception tree used by this library.

Note: Some functions throw ordinary python base exceptions as well.

exception simplezfs.exceptions.DatasetNotFound: A dataset was not found.

exception simplezfs.exceptions.PermissionError: Permissions are not sufficient to carry out the task.

exception simplezfs.exceptions.PoolNotFound: A pool was not found.

exception simplezfs.exceptions.PropertyNotFound: A property was not found.

exception simplezfs.exceptions.ValidationError: Indicates that a value failed validation.