zfsmgr - API for ZFS storage pools, datasets and snapshots
interface ZfsDataset ZfsDataset create_filesystem(string name, ZfsProp[] props, ZfsOpOption[] options); ZfsSnapshot create_snapshot(string name, ZfsProp[] props, ZfsOpOption[] options); destroy_snapshot(string name, ZfsOpOption[] options); rename_snapshot(string old_name, string new_name, ZfsOpOption[] options); string[] get_filesystems(boolean recursive); string[] get_snapshots(boolean recursive); destroy(ZfsOpOption[] options); rename(string new_name, ZfsOpOption[] options); mount(string[] mount_options, ZfsOpOption[] options); unmount(ZfsOpOption[] options); rollback(string snapshot_name, ZfsOpOption[] options); promote(); set_props(ZfsProp[] props); ZfsPropDetail[] get_props(ZfsPropRequest[] props); inherit(ZfsProp[] props, ZfsOpOption[] options); SendSocketInfo get_send_socket(string name, SocketType socket_type, boolean verify_token, ZfsOpOption[] options); SendStreamInfo get_send_stream_info(string name, ZfsOpOption[] options); RecvSocketInfo get_receive_socket(string name, SocketType socket_type, ZfsRecvNameOptions name_options, boolean verify_token, ZfsOpOption[] options, ZfsProp[] props); interface ZfsSnapshot ZfsDataset clone(string clone_name, ZfsProp[] props, ZfsOpOption[] options); string[] get_clones(); ZfsPropDetail[] get_props(ZfsPropRequest[] props); set_props(ZfsProp[] props); inherit(ZfsProp[] props); interface Zpool ZpoolVdev[] get_vdevs(); set_props(ZfsProp[] props); ZfsPropDetail[] get_props(ZfsPropRequest[] props); ZfsDataset get_dataset_ref(); interface ZfsUtil boolean valid_zfs_name(string name, boolean is_snapname);
ZFSMGR(3rad) RAD Module Definitions ZFSMGR(3rad)
NAME
zfsmgr - API for ZFS storage pools, datasets and snapshots
SYNOPSIS
interface ZfsDataset
ZfsDataset create_filesystem(string name,
ZfsProp[] props,
ZfsOpOption[] options);
ZfsSnapshot create_snapshot(string name,
ZfsProp[] props,
ZfsOpOption[] options);
destroy_snapshot(string name,
ZfsOpOption[] options);
rename_snapshot(string old_name,
string new_name,
ZfsOpOption[] options);
string[] get_filesystems(boolean recursive);
string[] get_snapshots(boolean recursive);
destroy(ZfsOpOption[] options);
rename(string new_name,
ZfsOpOption[] options);
mount(string[] mount_options,
ZfsOpOption[] options);
unmount(ZfsOpOption[] options);
rollback(string snapshot_name,
ZfsOpOption[] options);
promote();
set_props(ZfsProp[] props);
ZfsPropDetail[] get_props(ZfsPropRequest[] props);
inherit(ZfsProp[] props,
ZfsOpOption[] options);
SendSocketInfo get_send_socket(string name,
SocketType socket_type,
boolean verify_token,
ZfsOpOption[] options);
SendStreamInfo get_send_stream_info(string name,
ZfsOpOption[] options);
RecvSocketInfo get_receive_socket(string name,
SocketType socket_type,
ZfsRecvNameOptions name_options,
boolean verify_token,
ZfsOpOption[] options,
ZfsProp[] props);
interface ZfsSnapshot
ZfsDataset clone(string clone_name,
ZfsProp[] props,
ZfsOpOption[] options);
string[] get_clones();
ZfsPropDetail[] get_props(ZfsPropRequest[] props);
set_props(ZfsProp[] props);
inherit(ZfsProp[] props);
interface Zpool
ZpoolVdev[] get_vdevs();
set_props(ZfsProp[] props);
ZfsPropDetail[] get_props(ZfsPropRequest[] props);
ZfsDataset get_dataset_ref();
interface ZfsUtil
boolean valid_zfs_name(string name,
boolean is_snapname);
DESCRIPTION
API com.oracle.solaris.rad.zfsmgr
This API provides functionality for management of ZFS storage pools,
ZFS datasets and ZFS snapshots.
The following sample Python clients illustrate some simple interactions
with the module.
Example 1. Retrieve the list of zpools on the system. Print out the
name and size of each zpool.
import rad.bindings.com.oracle.solaris.rad.zfsmgr_1 as zfsmgr
import rad.connect as radcon
with radcon.connect_unix() as rc:
prop0 = zfsmgr.ZfsPropRequest(name="name")
# get the integer value for size
prop1 = zfsmgr.ZfsPropRequest(name="size", integer_val=True)
pools = rc.list_objects(zfsmgr.Zpool())
for pool in pools:
pobj = rc.get_object(pool)
pvalues = pobj.get_props([prop0, prop1])
for pv in pvalues:
print "%s:%s\t%s\n" % (pv.name, pv.value, str(pv.source))
Example 2. List all ZFS filesystems in 'rpool', including all
descendants.
import rad.bindings.com.oracle.solaris.rad.zfsmgr_1 as zfsmgr
import rad.client as radc
import rad.connect as radcon
with radcon.connect_unix() as rc:
name_pattern = radc.ADRGlobPattern({"name" : "rpool"})
rpool_ds_obj = rc.get_object(zfsmgr.ZfsDataset(), name_pattern)
all_children = rpool_ds_obj.get_filesystems(recursive=True)
for c in all_children:
print str(c)
Example 3. Destroy a ZFS filesystem called 'rpool/p1'. The 'rpool/p1'
filesystem does not have any descendant datasets.
import rad.bindings.com.oracle.solaris.rad.zfsmgr_1 as zfsmgr
import rad.client as radc
import rad.connect as radcon
with radcon.connect_unix() as rc:
name_pattern = radc.ADRGlobPattern({"name" : "rpool/p1"})
ds_obj = rc.get_object(zfsmgr.ZfsDataset(), name_pattern)
ds_obj.destroy()
Example 4. Destroy a ZFS filesystem called 'rpool/p2' with descendant
datasets. The recurse_filesystems option is specified so that the
descendant datasets are destroyed as well.
import rad.bindings.com.oracle.solaris.rad.zfsmgr_1 as zfsmgr
import rad.client as radc
import rad.connect as radcon
with radcon.connect_unix() as rc:
name_pattern = radc.ADRGlobPattern({"name" : "rpool/p2"})
zfs_obj = rc.get_object(zfsmgr.ZfsDataset(), name_pattern)
zfs_obj.destroy(options=[zfsmgr.ZfsOpOption.recurse_filesystems])
Example 5. Create ZFS filesystems 'rpool/p1' and 'rpool/p1/p2'. Create
a snapshot called 'snap1' for the 'rpool/p1' dataset and all of its
nested datasets.
import rad.bindings.com.oracle.solaris.rad.zfsmgr_1 as zfsmgr
import rad.client as radc
import rad.connect as radcon
with radcon.connect_unix() as rc:
name_pattern = radc.ADRGlobPattern({"name" : "rpool"})
rpool_obj = rc.get_object(zfsmgr.ZfsDataset(), name_pattern)
p1_obj = rpool_obj.create_filesystem(name="rpool/p1")
p2_obj = rpool_obj.create_filesystem(name="rpool/p1/p2")
my_snap = p1_obj.create_snapshot(name="rpool/p1@snap1",
options=[zfsmgr.ZfsOpOption.recurse_filesystems]);
Example 6. Do a zfs send of rpool/p1@snap, and a zfs receive to create
dataset space/recv_ds. An event handler is defined and registered for
both zfs send and zfs receive events so we will be notified of the
result of operations.
import socket
import rad.bindings.com.oracle.solaris.rad.zfsmgr_1 as zfsmgr
import rad.client as radc
import rad.connect as radcon
#
# This is the event handler that will get called for both the
# "zfs_send_status" and "zfs_recv_status" events.
#
def handler(event, payload, user):
print "Event: %s" % str(event)
print "Operation: %s" % str(payload.operation)
print "Return Code: %s" % str(payload.return_code)
if (payload.return_code != 0):
print "libzfs_errcode: %s" % str(payload.libzfs_errcode)
print "libzfs_errstr: %s" % str(payload.libzfs_errstr)
with radcon.connect_unix() as rc:
# get a handle to the "rpool/p1" filesystem
p1_ds_obj = rc.get_object(zfsmgr.ZfsDataset(),
radc.ADRGlobPattern({"name" : "rpool/p1"}))
# get a handle to the "space" filesystem
space_ds_obj = rc.get_object(zfsmgr.ZfsDataset(),
radc.ADRGlobPattern({"name" : "space"}))
# register to listen to events from those two objects
rc.subscribe(p1_ds_obj, "zfs_send_status", handler);
rc.subscribe(space_ds_obj, "zfs_recv_status", handler);
local_host = socket.gethostname()
# Create a send stream for the rpool/p1@snap snapshot. The
# data will be sent to the INET socket created by the
# get_send_socket() call.
send_sock_info = p1_ds_obj.get_send_socket(
name="rpool/p1@snap", socket_type=zfsmgr.SocketType.AF_INET)
send_sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
send_sock.connect((local_host, int(send_sock_info.socket)))
# Create a new filesystem called space/recv_ds using data from the
# read from the INET socket that's created by the
# get_receive_socket() call.
recv_sock_info = space_ds_obj.get_receive_socket(
name="space/recv_ds", socket_type=zfsmgr.SocketType.AF_INET,
name_options=zfsmgr.ZfsRecvNameOptions.use_provided_name)
recv_sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
recv_sock.connect((local_host, int(recv_sock_info.socket)))
buf_size = 1048576 # 1mb
while True:
# read the data from the send stream
buf = send_sock.recv(buf_size)
if not buf:
break
# write the data to the receive steam
recv_sock.send(buf)
recv_sock.close()
send_sock.close()
INTERFACES
interface ZfsDataset
This object represents a ZFS dataset and contains interfaces for
managing ZFS datasets.
ZfsDataset Methods
ZfsDataset create_filesystem(string name, ZfsProp[] props,
ZfsOpOption[] options)
Create a ZFS filesystem with the name and properties given. It
will be mounted according to the mountpoint property inherited
from the parent unless a mountpoint is specified in props. Upon
successful return, the ZfsDataset object may be used directly
for ZfsDataset related operations.
Arguments:
name -- Name of the new filesystem. The filesystem to be
created must be a descendant of this ZFS filesystem.
Intermediate descendants will be created if they do not exist
and the create_parent option is specified in options.
props (nullable) -- Optional list of name-value pairs of
properties to set.
options (nullable) -- A list of one or more values from the
ZfsOpOptions enum. This is an optional argument. For this
operation, the following options are allowed:
create_parent: create all non-existing parent datasets.
Equivalent to: zfs create -p
Result:
ZfsDataset -- A ZfsDataset object representing the ZFS
filesystem that was just created.
Error:
ZfsRADError
ZfsSnapshot create_snapshot(string name, ZfsProp[] props,
ZfsOpOption[] options)
Create a snapshot of this ZFS dataset.
Arguments:
name -- Name of the snapshot to be created.
props (nullable) -- Optional list of name-value pairs of
properties to set.
options (nullable) -- A list of one or more values from the
ZfsOpOptions enum. This is an optional argument. For this
operation, the following options are allowed:
recurse_filesystems: generate snapshots of all child
datasets. Snapshots will take the name of their
original dataset, suffixed by "@" and the
snapshot suffix provided by the "name" argument.
Equivalent to: zfs snapshot -r
Result:
ZfsSnapshot -- A ZfsSnapshot object representing the ZFS
snapshot created by this call.
Error:
ZfsRADError
destroy_snapshot(string name, ZfsOpOption[] options)
Destroy the specified snapshot.
Arguments:
name -- Name of the snapshot to be destroyed.
options (nullable) -- A list of one or more values from the
ZfsOpOptions enum. This is an optional argument. For this
operation, the following options are allowed:
defer: defer snapshot deletion.
Equivalent to: zfs destroy -d
recurse_filesystems: destroy all snapshots with
this name in the descendant filesystems.
Equivalent to: zfs destroy -r
recurse_dependents: recursively destroy dependents
Equivalent to: zfs destroy -R
Error:
ZfsRADError
rename_snapshot(string old_name, string new_name,
ZfsOpOption[] options)
Rename the specified snapshot.
Arguments:
old_name -- Name of the snapshot to be renamed
new_name -- New name for the snapshot
options (nullable) -- A list of one or more values from the
ZfsOpOptions enum. This is an optional argument. For this
operation, the following options are allowed:
recurse_filesystems: recursively rename the snapshots of
all descendant datasets.
Equivalent to: zfs rename -r
Error:
ZfsRADError
string[] get_filesystems(boolean recursive)
Get a list of this dataset's descendant ZFS filesystems.
Arguments:
recursive (nullable) -- Optional. Default is False, which only
returns the first level descendant of the filesystem. Set this
to True to get all descendant filesystems of this ZFS
filesystem.
Result:
string[] -- List of string names of descendant ZFS filesystems.
Error:
ZfsRADError
string[] get_snapshots(boolean recursive)
Get a list of this dataset's snapshots.
Arguments:
recursive (nullable) -- Optional. Default is False, which only
returns snapshots of the filesystem. Set this to True to get
snapshots from all descendant filesystems of this ZFS
filesystem.
Result:
string[] -- List of string names of this dataset's snapshots.
Error:
ZfsRADError
destroy(ZfsOpOption[] options)
Destroy this ZFS dataset. The handle to this dataset will be
invalid upon successful return.
Arguments:
options (nullable) -- A list of one or more values from the
ZfsOpOptions enum. This is an optional argument. For this
operation, the following options are allowed:
force_unmount: force unmount of any filesystems.
Equivalent to: zfs destroy -f
recurse_filesystems: destroy descendant filesystems.
Equivalent to: zfs destroy -r
recurse_dependents: recursively destroy dependents.
Equivalent to: zfs destroy -R
Error:
ZfsRADError
rename(string new_name, ZfsOpOption[] options)
Rename this ZFS dataset.
Arguments:
new_name -- String containing the new name.
options (nullable) -- A list of one or more values from the
ZfsOpOptions enum. This is an optional argument. For this
operation, the following options are allowed:
create_parent: create all non-existing parent datasets.
Equivalent to: zfs rename -p
Error:
ZfsRADError
mount(string[] mount_options, ZfsOpOption[] options)
Mount this ZFS dataset.
Arguments:
mount_options (nullable) -- Optional list of of mount options
to use for the duration of the mount. All mount options allowed
for the zfs(1M) mount command can be specified. Each option
should be specified as a separate string in the list.
options (nullable) -- A list of one or more values from the
ZfsOpOptions enum. This is an optional argument. For this
operation, the following options are allowed:
overlay_mount: perform an overlay mount
Equivalent to: zfs mount -O
Error:
ZfsRADError
unmount(ZfsOpOption[] options)
Unmount this ZFS dataset.
Arguments:
options (nullable) -- A list of one or more values from the
ZfsOpOptions enum. This is an optional argument. For this
operation, the following options are allowed:
force_unmount: force unmount, even if in use.
Equivalent to: zfs unmount -f
Error:
ZfsRADError
rollback(string snapshot_name, ZfsOpOption[] options)
Roll this dataset back to the named snapshot.
Arguments:
snapshot_name -- Name of the snapshot to roll back to.
options (nullable) -- A list of one or more values from the
ZfsOpOptions enum. This is an optional argument. For this
operation, the following options are allowed:
force_unmount: force unmount of any filesystems.
Equivalent to: zfs rollback -f
allow_destroy_snapshots: allow destroying snapshots more
recent than this one.
Equivalent to: zfs rollback -r
allow_destroy_clones: allow recursively destroying
snapshots more recent than this one, plus
any clones of those snapshots.
Equivalent to: zfs rollback -R
Error:
ZfsRADError
promote()
Promote this ZFS dataset. Dataset must be a clone.
Error:
ZfsRADError
set_props(ZfsProp[] props)
Set ZFS dataset properties.
Arguments:
props -- List of properties to set.
Error:
ZfsRADError -- The ZfsRADError contains information about the
first property that can not be set. No subsequent properties in
the list will be set after the first failure.
ZfsPropDetail[] get_props(ZfsPropRequest[] props)
Get ZFS dataset property information.
Arguments:
props -- List of properties to get.
Result:
ZfsPropDetail[] -- List of ZfsPropDetail objects, one for each
property requested in the get_props() function call. The
ZfsPropDetail object contains name, value, source and error
fields. Their values are set based on the result of getting
each property. If the property was successfully retrieved, then
the name, value and source will have appropriate values and
error will be None. If the property is valid, but does not have
a value, then the name field is set to the name of the
requested property, and all other fields will be None. If the
property was not successfully retrieved, the name field is set
to the name of the requested property, and the error field will
be set with details on the error.
Error:
ZfsRADError -- Returns any error not specific to getting
property values. Errors related to getting a specific property
value are included in the property detail structure that is
returned.
inherit(ZfsProp[] props, ZfsOpOption[] options)
Clears the specified properties, causing them to be inherited
from an ancestor. If no ancestor has the property set, then the
default value is used.
Arguments:
props -- List of properties to clear. Only the name field of
the ZfsProp structure is used.
options (nullable) -- A list of one or more values from the
ZfsOpOptions enum. This is an optional argument. For this
operation, the following options are allowed:
recurse_filesystems: recursively inherits the
given properties for all children
Equivalent to: zfs inherit -r
revert_received: Reverts to the received property
value, if any.
Equivalent to: zfs inherit -S
Error:
ZfsRADError
SendSocketInfo get_send_socket(string name, SocketType socket_type,
boolean verify_token, ZfsOpOption[] options)
Open a socket for sending the stream representation of the
specified ZfsSnapshot. This is similar to the "zfs send"
command. Only functionality provided by -r, -R, -C and -p from
the "zfs send" command is supported. Incremental streams are
not supported.
Arguments:
name -- Name of the snapshot to be sent.
socket_type -- The type of socket to create
verify_token (nullable) -- Specify whether token verification
is required before data is sent. This is an optional argument.
If not specified, it defaults to False, which means a client
can connect to the port and start receiving the zfs send
stream's data without sending the generated token returned in
this call.
options (nullable) -- A list of one or more values from the
ZfsOpOptions enum. This is an optional argument. For this
operation, the following options are allowed:
recurse_filesystems: Generates a recursive stream
package. A recursive stream package contains
a series of full and/or incremental streams.
When received, all properties and descendant file
systems are preserved.
Equivalent to: zfs send -r
self_contained: Creates a self-contained stream.
Valid only with the recurse_filesystems option.
Equivalent to: zfs send -C
send_props: Sends properties.
Equivalent to: zfs send -p
recurse_dependents: Generates a replication stream package
that replicates the specified filesystem and
all descendant filesystems.
Equivalent to: zfs send -R
Result:
SendSocketInfo -- SendSocketInfo structure containing
information about the send stream, and the socket to use for
the connection
Error:
ZfsRADError
SendStreamInfo get_send_stream_info(string name,
ZfsOpOption[] options)
Get information about the ZFS stream that would be generated
with the options provided without actually creating the stream.
Arguments:
name -- Name of the snapshot to get send information from
options (nullable) -- A list of one or more values from the
ZfsOpOptions enum. This is an optional argument. For this
operation, the following options are allowed:
recurse_filesystems: Generates a recursive stream
package. A recursive stream package contains
a series of full and/or incremental streams.
When received, all properties and descendant file
systems are preserved.
Equivalent to: zfs send -r
self_contained: Creates a self-contained stream.
Valid only with the recurse_filesystems option.
Equivalent to: zfs send -C
send_props: Sends properties.
Equivalent to: zfs send -p
recurse_dependents: Generates a replication stream package
that replicates the specified filesystem and
all descendant filesystems.
Equivalent to: zfs send -R
Result:
SendStreamInfo -- SendStreamInfo structure containing
information about the snapshots that would be sent as well as
the estimated size of the stream.
Error:
ZfsRADError
RecvSocketInfo get_receive_socket(string name,
SocketType socket_type, ZfsRecvNameOptions name_options,
boolean verify_token, ZfsOpOption[] options, ZfsProp[] props)
Open a socket to receive the data for creating a ZfsSnapshot or
a ZfsDataset. Depending on the options specified, and whether
the provided stream is a full stream or an incremental stream,
the dataset will be modified differently. If the incoming
stream is a full stream, and the specified dataset does not
exist, the incoming stream will be received into a newly
created dataset that is a descendant of this dataset.
Otherwise, the incoming stream will modify this dataset based
on user specified options.
Arguments:
name -- Name of ZFS dataset or snapshot to create from the
received stream of data.
The provided dataset name or the top level dataset of the
provided name must match the name of this dataset.
socket_type -- Type of socket to create.
name_options -- Specifies how the final name used for the
ZfsSnapshot or ZfsDataset should be derived.
verify_token (nullable) -- Specify whether token verification
is required before data is received. This is an optional
argument. If not specified, it defaults to False, which means a
client can connect to the port and start sending the data to
the zfs receive stream without first sending the generated
token returned in this call.
options (nullable) -- A list of one or more values from the
ZfsOpOptions enum. This is an optional argument. For this
operation, the following options are allowed:
force_rollback: Forces a rollback of the filesystem
to the most recent snapshot before performing
the receive operation.
Equivalent to: zfs receive -F
do_not_mount: File system that is associated with
the received stream is not mounted.
Equivalent to: zfs receive -u
props (nullable) -- Optional list of name-value pairs of
properties to set. If a "name" property is included, it must
match the "name" argument.
Result:
RecvSocketInfo -- SocketInfo structure with information for
socket to use for the connection.
Error:
ZfsRADError
ZfsDataset Events
ZfsSendRecvStatus zfs_send_status
ZfsSendRecvStatus zfs_recv_status
interface ZfsSnapshot
This object represents a ZFS snapshot and contains interfaces for
managing ZFS snapshots. This object does not provide an interface for
creating snapshots. Snapshot creation should be done by calling
ZfsDataset's create_snapshot() interface.
ZfsSnapshot Methods
ZfsDataset clone(string clone_name, ZfsProp[] props,
ZfsOpOption[] options)
Clone a dataset from this snapshot.
Arguments:
clone_name -- Name of the new dataset.
props (nullable) -- Optional list of name-value pairs of
properties to set in the clone. If a "name" property is
included, it must match the "name" argument. Equivalent to: zfs
clone -o
options (nullable) -- A list of one or more values from the
ZfsOpOptions enum. This is an optional argument. For this
operation, the following option is allowed:
create_parent: create all non-existing parent datasets
of the clone. Equivalent to: zfs clone -p
Result:
ZfsDataset -- A ZfsDataset object representing the ZFS dataset
created from cloning this snapshot.
Error:
ZfsRADError
string[] get_clones()
Get all the datasets that are clones of this snapshot.
Result:
string[] -- List of clone dataset names.
Error:
ZfsRADError
ZfsPropDetail[] get_props(ZfsPropRequest[] props)
Get ZFS snapshot property information.
Arguments:
props -- List of properties to get.
Result:
ZfsPropDetail[] -- List of ZfsPropDetail objects, one for each
property requested in the get_props() function call. The
ZfsPropDetail object contains name, value, source and error
fields. Their values are set based on the result of getting
each property. If the property was successfully retrieved, then
the name, value and source will have appropriate values and
error will be None. If the property is valid, but does not have
a value, then the name field is set to the name of the
requested property, and all other fields will be None. If the
property was not successfully retrieved, the name field is set
to the name of the requested property, and the error field will
be set with details on the error.
Error:
ZfsRADError -- Returns any error not specific to getting
property values. Errors related to getting a specific property
value are included in the property detail structure that is
returned.
set_props(ZfsProp[] props)
Set ZFS snapshot properties.
Arguments:
props -- List of properties to set.
Error:
ZfsRADError -- The ZfsRADError contains information about the
first property that can not be set. No subsequent properties in
the list will be set after the first failure.
inherit(ZfsProp[] props)
Clears the specified properties, causing them to be inherited
from an ancestor. If no ancestor has the property set, then the
default value is used.
Arguments:
props -- List of properties to clear. Only the name field of
the ZfsProp structure is used.
Error:
ZfsRADError
interface Zpool
Zpools are assumed to already exist on the system. Thus, the Zpool
interfaces limit zpool operations to listing vdev configuration and
getting/setting zpool properties. Note that there is no
get_filesystems() method. The root dataset's get_filesystems() method
should be used to get all filesystems in a zpool.
Zpool Methods
ZpoolVdev[] get_vdevs()
Return the vdev configuration of this zpool.
Result:
ZpoolVdev[] -- A list of ZpoolVdev structs.
Error:
ZfsRADError
set_props(ZfsProp[] props)
Set Zpool properties.
Arguments:
props -- List of properties to set.
Error:
ZfsRADError -- The ZfsRADError contains information about the
first property that can not be set. No subsequent properties in
the list will be set after the first failure.
ZfsPropDetail[] get_props(ZfsPropRequest[] props)
Get Zpool property information.
Arguments:
props -- List of properties to get.
Result:
ZfsPropDetail[] -- List of ZfsPropDetail objects, one for each
property requested in the get_props() function call. The
ZfsPropDetail object contains name, value, source and error
fields. Their values are set based on the result of getting
each property. If the property was successfully retrieved, then
the name, value and source will have appropriate values and
error will be None. If the property is valid, but does not have
a value, then the name field is set to the name of the
requested property, and all other fields will be None. If the
property was not successfully retrieved, the name field is set
to the name of the requested property, and the error field will
be set with details on the error.
Error:
ZfsRADError -- Returns any error not specific to getting
property values. Errors related to getting a specific property
value are included in the property detail structure that is
returned.
ZfsDataset get_dataset_ref()
Return a reference to a ZfsDataset object representing this
zpool.
Result:
ZfsDataset -- A ZfsDataset object representing this zpool.
Error:
ZfsRADError
interface ZfsUtil
This is a singleton instance providing ZFS functionality that is
unrelated to Zpool, ZfsDataset or ZfsSnapshot.
ZfsUtil Methods
boolean valid_zfs_name(string name, boolean is_snapname)
Check whether the specified string can be used as a ZFS name
Arguments:
name
is_snapname (nullable) -- Optional. Specify whether the name to
be verified is a snapshot name or not. If not specified, the
provided name is assumed to be a dataset name.
Result:
boolean -- True will be returned if the given name can be used
as a ZFS name. False will be returned otherwise.
ENUMERATED TYPES
enum PropSrc -- The source for ZFS/Zpool property value.
src_local (0) -- property source: local
src_default (1) -- property source: default
src_temporary (2) -- property source: temporary
src_received (3) -- property source: received
src_inherited (4) -- property source: inherited
src_none (5) -- property source: none
enum ZfsOpOption -- Options for ZfsDataset/Zpool/ZfsSnapshot
operations.
These options do not apply to all operations. See the actual API
for a description of which options are allowed.
create_parent (0) -- create all non-existing parent datasets
recurse_filesystems (1) -- perform the specified operation
recursively on all descendants of the given filesystems. Similar to
-r in zfs(1M)
recurse_dependents (2) -- perform the specified operation
recursively on all dependents of the given filesystems. Similar to
-R in zfs(1M)
defer (3) -- defer deletion of the given snapshot
overlay_mount (4) -- perform an overlay mount
force_unmount (5) -- force unmount of any mounted filesystems
force_rollback (6) -- force rollback of a filesystem
do_not_mount (7) -- do not mount the filesystem that is associated
with the received stream
send_props (8) -- send the properties in the "zfs send" stream
self_contained (9) -- create a self-contained "zfs send" stream
revert_received (10) -- revert to the received property value, if
any
allow_destroy_snapshots (11) -- allow destruction of snapshots in a
rollback operation
allow_destroy_clones (12) -- allow destruction of clones in a
rollback operation
enum ZfsRecvNameOptions -- Options to control how the name of the
ZfsSnapshot or ZfsDataset from the get_receive_socket function is
generated.
use_provided_name (0) -- Use the snapshot or dataset name exactly
as provided.
use_all_but_pool_name (1) -- All but the pool name of the sent
snapshot path is appended to the string provided in the name
argument. Equivalent to the -d option in the zfs receive
subcommand.
use_tail_only (2) -- Only the tail of the sent snapshot path is
appended to the string provided in the name argument. Equivalent to
the -e option in the zfs receive subcommand.
enum ZfsRADErrType -- Error types
libzfs_err (0) -- Errors from libzfs calls made by the ZFS RAD
module
zfsrad_err (1) -- Errors from the ZFS RAD module
operation_err (2) -- Errors from the requested operation
enum SocketType -- Socket types that can be created for zfs
send/receive.
AF_UNIX (0) -- Unix domain socket
AF_INET (1) -- networking socket
STRUCTURE TYPES
struct ZfsRADError -- Contains information about an error that occurred
in the ZFS RAD module.
The err_type field indicates the type of error. Certain fields in
this object are only used for certain error types. See each field
for details.
Fields:
ZfsRADErrType err_type
Contains information about the type of error
integer libzfs_errcode
libzfs Error code (enumerated type). This is only used for
"libzfs_err" type.
string libzfs_errstr (nullable)
Error string corresponding to libzfs error code. This is only
used for "libzfs_err" type.
string info (nullable)
For "zfsrad_err" error type, this field contains detailed
information about the error. For "libzfs_err", and
"operation_err" error type, this field might contain additional
information about the condition under which the error occurred.
string location (nullable)
Returns the function where the error occurred.
struct ZfsProp -- Structure for specifying ZFS property information.
Fields:
string name
Property name
string value
Property value
struct ZfsPropDetail -- Structure for returning ZFS property
information by the get_props() functions.
Fields:
string name
Property name
string value (nullable)
Property value - If the property is valid, but there is no
value defined for the property, the value will be None.
PropSrc source
The source of the property (similar to what is returned by the
get subcommand for zfs(1M)).
ZfsRADError error (nullable)
If this is not set, it means the value retrieved by the
get_prop() function is successful. If there is any problem with
retrieving the property, this will contain the error
information.
struct ZfsPropRequest -- Structure used for requesting ZFS property
information for the get_props() functions.
Fields:
string name
Property name
boolean persistent (nullable)
Specify whether the get_props() request should return the
persistent value of the property or not. This is an optional
argument. If not specified, this defaults to False, and the
effective value of the property will be returned. If this is
set to True, the "received" field for this property request may
not have the value of True.
boolean received (nullable)
Specify whether the get_props() request should return the
received value of the property or not. This is an optional
argument. If not specified, this defaults to False, and the
effective value of the property will be returned. If this is
set to True, the "persistent" field for this property request
may not have the value of True.
boolean integer_val (nullable)
Specify whether the get property request should return the
requested property's value in integer format. This is an
optional argument. If not specified, this defaults to False,
and the returned value will be in string format.
struct SendStreamInfo -- Contains information about the stream that
will be generated.
Fields:
string size
Estimated size of the stream to be generated. The data type is
a string instead of a integer because the size might be bigger
than a 32 bit integer.
string[] snapshot_info
List of information about the send stream.
struct SendSocketInfo -- Contains information about the socket to be
used for the ZFS stream.
Fields:
string token (nullable)
Token used to confirm that the connection is valid.
string socket
If the requested socket type is a UNIX domain socket, then this
will be the path to the socket file. If the requested socket
type is an INET socket, then the value will be the connection
port number.
SendStreamInfo stream_info
Information about the send stream.
struct RecvSocketInfo -- Contains information about the socket to be
used for the ZFS stream.
Fields:
string token (nullable)
Token used to confirm that the connection is valid.
string socket
If the requested socket type is a UNIX domain socket, then this
will be the path to the socket file. If the requested socket
type is an INET socket, then the value will be the connection
port number.
struct ZpoolVdev -- Zpool Vdev configuration information.
Fields:
string type
Type of the Vdev. Only types "mirror", "disk" and "file" are
supported at this time.
string[] devices
A list of devices making up this Vdev
struct ZfsSendRecvStatus -- Return status of the send/receive
operation.
Fields:
string operation
Indicates whether this is a "send" or "receive" operation.
integer return_code
The return code from the zfs_send() or zfs_receive() call.
integer libzfs_errcode
libzfs.so error code as defined in /usr/include/libzfs.h. This
is only used if there is an error.
string libzfs_errstr (nullable)
Error string corresponding to libzfs error code. This is only
used if there is an error.
string info (nullable)
Optional field for additional information for the client.
Version: (1.0)
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
+--------------------+-------------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-------------------------+
|Availability | system/management/rad/* |
+--------------------+-------------------------+
|Interface Stability | Private |
+--------------------+-------------------------+
SEE ALSO
rad(1M)
SunOS 5.11 2017-01-11 ZFSMGR(3rad)