Documentation ¶
Overview ¶
Package zfs provides wrappers around the ZFS command line tools.
Index ¶
- Constants
- Variables
- func ListWithProperty(ctx context.Context, tp DatasetType, parentDataset, prop string) (map[string]string, error)
- func ResumeSend(ctx context.Context, output io.Writer, resumeToken string, ...) error
- func TestZPool(zpool string, fn func())
- type CloneOptions
- type CommandError
- type CountReader
- type CreateFilesystemOptions
- type CreateVolumeOptions
- type Dataset
- func CreateFilesystem(ctx context.Context, name string, options CreateFilesystemOptions) (*Dataset, error)
- func CreateVolume(ctx context.Context, name string, size uint64, options CreateVolumeOptions) (*Dataset, error)
- func GetDataset(ctx context.Context, name string, extraProperties ...string) (*Dataset, error)
- func ListDatasets(ctx context.Context, options ListOptions) ([]Dataset, error)
- func ListFilesystems(ctx context.Context, options ListOptions) ([]Dataset, error)
- func ListSnapshots(ctx context.Context, options ListOptions) ([]Dataset, error)
- func ListVolumes(ctx context.Context, options ListOptions) ([]Dataset, error)
- func ReceiveSnapshot(ctx context.Context, input io.Reader, name string, options ReceiveOptions) (*Dataset, error)
- func (d *Dataset) Children(ctx context.Context, options ListOptions) ([]Dataset, error)
- func (d *Dataset) Clone(ctx context.Context, dest string, options CloneOptions) (*Dataset, error)
- func (d *Dataset) Destroy(ctx context.Context, options DestroyOptions) error
- func (d *Dataset) GetProperty(ctx context.Context, key string) (string, error)
- func (d *Dataset) InheritProperty(ctx context.Context, key string) error
- func (d *Dataset) LoadKey(ctx context.Context, options LoadKeyOptions) error
- func (d *Dataset) Mount(ctx context.Context, options MountOptions) (*Dataset, error)
- func (d *Dataset) Promote(ctx context.Context) error
- func (d *Dataset) Rename(ctx context.Context, name string, options RenameOptions) (*Dataset, error)
- func (d *Dataset) Rollback(ctx context.Context, options RollbackOptions) error
- func (d *Dataset) SendSnapshot(ctx context.Context, output io.Writer, options SendOptions) error
- func (d *Dataset) SetProperty(ctx context.Context, key, val string) error
- func (d *Dataset) Snapshot(ctx context.Context, name string, options SnapshotOptions) (*Dataset, error)
- func (d *Dataset) Snapshots(ctx context.Context, options ListOptions) ([]Dataset, error)
- func (d *Dataset) UnloadKey(ctx context.Context, options UnloadKeyOptions) error
- func (d *Dataset) Unmount(ctx context.Context, options UnmountOptions) (*Dataset, error)
- type DatasetType
- type DestroyOptions
- type ListOptions
- type LoadKeyOptions
- type MountOptions
- type ProgressCallback
- type ReceiveOptions
- type RenameOptions
- type ResumableStreamError
- type ResumeSendOptions
- type RollbackOptions
- type SendOptions
- type SnapshotOptions
- type UnloadKeyOptions
- type UnmountOptions
Constants ¶
const ( PropertyAvailable = "available" PropertyCanMount = "canmount" PropertyCompression = "compression" PropertyEncryption = "encryption" PropertyKeyFormat = "keyformat" PropertyKeyStatus = "keystatus" PropertyKeyLocation = "keylocation" PropertyLogicalUsed = "logicalused" PropertyMounted = "mounted" PropertyMountPoint = "mountpoint" PropertyName = "name" PropertyOrigin = "origin" PropertyQuota = "quota" PropertyReferenced = "referenced" PropertyRefQuota = "refquota" PropertyReadOnly = "readonly" PropertyReceiveResumeToken = "receive_resume_token" PropertyType = "type" PropertyUsed = "used" PropertyUsedByDataset = "usedbydataset" PropertyVolSize = "volsize" PropertyWritten = "written" PropertyYes = "yes" PropertyOn = "on" PropertyNo = "no" PropertyOff = "off" PropertyUnset = "-" EncryptionAES128CCM = "aes-128-ccm" EncryptionAES192CCM = "aes-192-ccm" EncryptionAES256CCM = "aes-256-ccm" EncryptionAES128GCM = "aes-128-gcm" EncryptionAES192GCM = "aes-192-gcm" EncryptionAES256GCM = "aes-256-gcm" KeyFormatHex = "hex" KeyFormatPassphrase = "passphrase" KeyFormatRaw = "raw" KeyLocationPrompt = "prompt" KeyStatusAvailable = "available" CanMountNoAuto = "noauto" )
const (
Binary = "zfs"
)
Variables ¶
var ( // ErrDatasetNotFound is returned when the dataset was not found ErrDatasetNotFound = errors.New("dataset not found") // ErrOnlySnapshotsSupported is returned when a snapshot only action is executed on another type of dataset ErrOnlySnapshotsSupported = errors.New("only snapshots are supported for this action") // ErrSnapshotsNotSupported is returned when an unsupported action is executed on a snapshot ErrSnapshotsNotSupported = errors.New("snapshots are not supported for this action") // ErrPoolOrDatasetBusy is returned when an action fails because ZFS is doing another action ErrPoolOrDatasetBusy = errors.New("pool or dataset busy") )
Functions ¶
func ListWithProperty ¶
func ListWithProperty(ctx context.Context, tp DatasetType, parentDataset, prop string) (map[string]string, error)
ListWithProperty returns a map of dataset names mapped to the properties value for datasets which have the given ZFS property.
func ResumeSend ¶
func ResumeSend(ctx context.Context, output io.Writer, resumeToken string, options ResumeSendOptions) error
ResumeSend resumes an interrupted ZFS stream of a snapshot to the input io.Writer using the receive_resume_token. An error will be returned if the input dataset is not of snapshot type.
Types ¶
type CloneOptions ¶
type CloneOptions struct { // Properties to be applied to the new dataset Properties map[string]string // Creates all the non-existing parent datasets. Datasets created in this manner are automatically mounted according // to the mountpoint property inherited from their parent. If the target filesystem or volume already exists, // the operation completes successfully. CreateParents bool }
CloneOptions are options you can specify to customize the clone command
type CommandError ¶
CommandError is an error which is returned when the `zfs` or `zpool` shell commands return with a non-zero exit code.
func (CommandError) Error ¶
func (e CommandError) Error() string
CommandError returns the string representation of an CommandError.
type CountReader ¶
CountReader counts the bytes it has read
func NewCountReader ¶
func NewCountReader(reader io.Reader) *CountReader
NewCountReader creates a new CountReader
func (*CountReader) Count ¶
func (r *CountReader) Count() int64
func (*CountReader) SetProgressCallback ¶
func (r *CountReader) SetProgressCallback(every time.Duration, progressFn ProgressCallback)
SetProgressCallback sets a new progress handler every duration
type CreateFilesystemOptions ¶
type CreateFilesystemOptions struct { // Sets the specified properties as if the command zfs set property=value was invoked at the same time the dataset was created. Properties map[string]string // Creates all the non-existing parent datasets. Datasets created in this manner are automatically mounted according // to the mountpoint property inherited from their parent. Any property specified on the command line using the -o option // is ignored. If the target filesystem already exists, the operation completes successfully. CreateParents bool // Do a dry-run creation. No datasets will be created. This is useful in conjunction with the -v or -P flags // to validate properties that are passed via -o options and those implied by other options. The actual dataset creation // can still fail due to insufficient privileges or available capacity. DryRun bool // Do not mount the newly created file system. NoMount bool // Provide input to stdin, for instance for loading keys Stdin io.Reader }
CreateFilesystemOptions are options you can specify to customize the create filesystem command
type CreateVolumeOptions ¶
type CreateVolumeOptions struct { // Sets the specified properties as if the command zfs set property=value was invoked at the same time the dataset was created. Properties map[string]string // Creates all the non-existing parent datasets. Datasets created in this manner are automatically mounted according // to the mountpoint property inherited from their parent. Any property specified on the command line using the -o option // is ignored. If the target filesystem already exists, the operation completes successfully. CreateParents bool // Creates a sparse volume with no reservation. Sparse bool // Do a dry-run creation. No datasets will be created. This is useful in conjunction with the -v or -P flags // to validate properties that are passed via -o options and those implied by other options. The actual dataset creation // can still fail due to insufficient privileges or available capacity. DryRun bool // Provide input to stdin, for instance for loading keys Stdin io.Reader }
CreateVolumeOptions are options you can specify to customize the create volume command
type Dataset ¶
type Dataset struct { Name string `json:"Name"` Type DatasetType `json:"Type"` Origin string `json:"Origin"` Used uint64 `json:"Used"` Available uint64 `json:"Available"` Mountpoint string `json:"Mountpoint"` Compression string `json:"Compression"` Written uint64 `json:"Written"` Volsize uint64 `json:"Volsize"` Logicalused uint64 `json:"Logicalused"` Usedbydataset uint64 `json:"Usedbydataset"` Quota uint64 `json:"Quota"` Refquota uint64 `json:"Refquota"` Referenced uint64 `json:"Referenced"` ExtraProps map[string]string `json:"ExtraProps"` }
Dataset is a ZFS dataset. A dataset could be a clone, filesystem, snapshot, or volume. The Type struct member can be used to determine a dataset's type.
The field definitions can be found in the ZFS manual: https://openzfs.github.io/openzfs-docs/man/7/zfsprops.7.html.
func CreateFilesystem ¶
func CreateFilesystem(ctx context.Context, name string, options CreateFilesystemOptions) (*Dataset, error)
CreateFilesystem creates a new ZFS filesystem with the specified name and properties.
A full list of available ZFS properties may be found in the ZFS manual: https://openzfs.github.io/openzfs-docs/man/7/zfsprops.7.html.
func CreateVolume ¶
func CreateVolume(ctx context.Context, name string, size uint64, options CreateVolumeOptions) (*Dataset, error)
CreateVolume creates a new ZFS volume with the specified name, size, and properties.
A full list of available ZFS properties may be found in the ZFS manual: https://openzfs.github.io/openzfs-docs/man/7/zfsprops.7.html.
func GetDataset ¶
GetDataset retrieves a single ZFS dataset by name. This dataset could be any valid ZFS dataset type, such as a clone, filesystem, snapshot, or volume.
func ListDatasets ¶
func ListDatasets(ctx context.Context, options ListOptions) ([]Dataset, error)
ListDatasets lists the datasets by type and allows you to fetch extra custom fields
func ListFilesystems ¶
func ListFilesystems(ctx context.Context, options ListOptions) ([]Dataset, error)
ListFilesystems returns a slice of ZFS filesystems. A filter argument may be passed to select a filesystem with the matching name, or empty string ("") may be used to select all filesystems.
func ListSnapshots ¶
func ListSnapshots(ctx context.Context, options ListOptions) ([]Dataset, error)
ListSnapshots returns a slice of ZFS snapshots. A filter argument may be passed to select a snapshot with the matching name, or empty string ("") may be used to select all snapshots.
func ListVolumes ¶
func ListVolumes(ctx context.Context, options ListOptions) ([]Dataset, error)
ListVolumes returns a slice of ZFS volumes. A filter argument may be passed to select a volume with the matching name, or empty string ("") may be used to select all volumes.
func ReceiveSnapshot ¶
func ReceiveSnapshot(ctx context.Context, input io.Reader, name string, options ReceiveOptions) (*Dataset, error)
ReceiveSnapshot receives a ZFS stream from the input io.Reader. A new snapshot is created with the specified name, and streams the input data into the newly-created snapshot.
func (*Dataset) Children ¶
Children returns a slice of children of the receiving ZFS dataset. A recursion depth may be specified, or a depth of 0 allows unlimited recursion.
func (*Dataset) Clone ¶
Clone clones a ZFS snapshot and returns a clone dataset. An error will be returned if the input dataset is not of snapshot type.
func (*Dataset) Destroy ¶
func (d *Dataset) Destroy(ctx context.Context, options DestroyOptions) error
Destroy destroys a ZFS dataset. If the destroy bit flag is set, any descendents of the dataset will be recursively destroyed, including snapshots. If the deferred bit flag is set, the snapshot is marked for deferred deletion.
func (*Dataset) GetProperty ¶
GetProperty returns the current value of a ZFS property from the receiving dataset.
A full list of available ZFS properties may be found in the ZFS manual: https://openzfs.github.io/openzfs-docs/man/7/zfsprops.7.html.
func (*Dataset) InheritProperty ¶
InheritProperty clears a property from the receiving dataset, making it use its parent datasets value.
func (*Dataset) LoadKey ¶
func (d *Dataset) LoadKey(ctx context.Context, options LoadKeyOptions) error
LoadKey loads the encryption key for this and optionally children datasets. See: https://openzfs.github.io/openzfs-docs/man/8/zfs-load-key.8.html
func (*Dataset) Promote ¶ added in v0.9.9
Promote promotes a cloned dataset to no longer depend on origin snapshot. An error will be returned if the input dataset is not of snapshot type. The
func (*Dataset) Rollback ¶
func (d *Dataset) Rollback(ctx context.Context, options RollbackOptions) error
Rollback rolls back the ZFS dataset to a previous snapshot. Optionally, intermediate snapshots can be destroyed. A ZFS snapshot rollback cannot be completed without the option DestroyMoreRecent, if more recent snapshots exist. An error will be returned if the input dataset is not of snapshot type.
func (*Dataset) SendSnapshot ¶
SendSnapshot sends a ZFS stream of a snapshot to the input io.Writer. An error will be returned if the input dataset is not of snapshot type.
func (*Dataset) SetProperty ¶
SetProperty sets a ZFS property on the receiving dataset.
A full list of available ZFS properties may be found in the ZFS manual: https://openzfs.github.io/openzfs-docs/man/7/zfsprops.7.html.
func (*Dataset) Snapshot ¶
func (d *Dataset) Snapshot(ctx context.Context, name string, options SnapshotOptions) (*Dataset, error)
Snapshot creates a new ZFS snapshot of the receiving dataset, using the specified name. Optionally, the snapshot can be taken recursively, creating snapshots of all descendent filesystems in a single, atomic operation.
func (*Dataset) UnloadKey ¶
func (d *Dataset) UnloadKey(ctx context.Context, options UnloadKeyOptions) error
UnloadKey unloads the encryption key for this dataset and optionally for child datasets as well. See: https://openzfs.github.io/openzfs-docs/man/8/zfs-unload-key.8.html
type DatasetType ¶
type DatasetType string
DatasetType is the zfs dataset type
const ( DatasetAll DatasetType = "all" DatasetFilesystem DatasetType = "filesystem" DatasetSnapshot DatasetType = "snapshot" DatasetVolume DatasetType = "volume" )
ZFS dataset types, which can indicate if a dataset is a filesystem, snapshot, or volume.
type DestroyOptions ¶
type DestroyOptions struct { // Recursively destroy all children. Recursive bool // Recursively destroy all dependents, including cloned file systems outside the target hierarchy. RecursiveClones bool // Forcibly unmount file systems. This option has no effect on non-file systems or unmounted file systems. Force bool // Do a dry-run (no-op) deletion. No data will be deleted. DryRun bool // Only for snapshots. Destroy immediately. If a snapshot cannot be destroyed now, mark it for deferred destruction. Defer bool }
DestroyOptions are options you can specify to customize the destroy command
type ListOptions ¶
type ListOptions struct { // ParentDataset filters by parent dataset, empty lists all ParentDataset string // DatasetType filters the results by type DatasetType DatasetType // ExtraProperties lists the properties to retrieve besides the ones in the Dataset struct (in the ExtraProps key) ExtraProperties []string // Recursive, if true will list all under the parent dataset Recursive bool // Depth specifies the depth to go below the parent dataset (or root if no parent) // Recursively display any children of the dataset, limiting the recursion to depth. // A depth of 1 will display only the dataset and its direct children. Depth int // FilterSelf: When true, it will filter out the parent dataset itself from the results FilterSelf bool }
ListOptions are options you can specify to customize the list command
type LoadKeyOptions ¶
type LoadKeyOptions struct { // Recursively loads the keys for the specified filesystem and all descendent encryption roots. Recursive bool // Do a dry-run (no-op) load-key. This will cause zfs to simply check that the provided key is correct. // This command may be run even if the key is already loaded. DryRun bool // When the key is in a file, load it using this keylocation. // This is optional when the ZFS dataset already has this property set. KeyLocation string // Provide a reader to read the key from stdin KeyReader io.Reader }
LoadKeyOptions are options you can specify to customize the load-key command
type MountOptions ¶
type MountOptions struct { // Perform an overlay mount. Allows mounting in non-empty mountpoint. OverlayMount bool // An optional, comma-separated list of mount options to use temporarily for the duration of the mount. Options []string // Load keys for encrypted filesystems as they are being mounted. This is equivalent to executing zfs load-key // on each encryption root before mounting it. Note that if a filesystem has keylocation=prompt, this will cause // the terminal to interactively block after asking for the key. LoadKeys bool }
MountOptions are options you can specify to customize the mount command
type ProgressCallback ¶
type ProgressCallback func(bytes int64)
ProgressCallback is a callback function that lets you monitor progress
type ReceiveOptions ¶
type ReceiveOptions struct { // Whether the received snapshot should be resumable on interrupions, or be thrown away Resumable bool // Properties to be applied to the dataset Properties map[string]string // EnableCompression enables zstd decompression EnableDecompression bool }
ReceiveOptions are options you can specify to customize the receive command
type RenameOptions ¶
type RenameOptions struct { // Creates all the nonexistent parent datasets. Datasets created in this manner are automatically mounted // according to the mountpoint property inherited from their parent. CreateParent bool // Recursively rename the snapshots of all descendent datasets. Snapshots are the only dataset that can // be renamed recursively. Recursive bool // Do not remount file systems during rename. If a file system's mountpoint property is set to legacy or none, // the file system is not unmounted even if this option is not given. NoMount bool // Force unmount any file systems that need to be unmounted in the process. This flag has no effect if used together // with the no mount flag. Force bool }
RenameOptions are options you can specify to customize the rename command
type ResumableStreamError ¶
type ResumableStreamError struct { CommandError ReceiveResumeToken string }
ResumableStreamError is returned when a zfs send is interrupted and contains the token with which the send can be resumed.
func (ResumableStreamError) ResumeToken ¶
func (e ResumableStreamError) ResumeToken() string
ResumeToken returns the resume token for this send
type ResumeSendOptions ¶
type ResumeSendOptions struct { // When set, uses a rate-limiter to limit the flow to this amount of bytes per second BytesPerSecond int64 // CompressionLevel is the level of zstd compression, zero for off CompressionLevel zstd.EncoderLevel }
ResumeSendOptions are options you can specify to customize the send resume command
type RollbackOptions ¶
type RollbackOptions struct { // Destroy any snapshots and bookmarks more recent than the one specified. DestroyMoreRecent bool // Destroy any more recent snapshots and bookmarks, as well as any clones of those snapshots. DestroyMoreRecentClones bool // Used with the DestroyMoreRecentClones option to force an unmount of any clone file systems that are to be destroyed. Force bool }
RollbackOptions are options you can specify to customize the rollback command
type SendOptions ¶
type SendOptions struct { // For encrypted datasets, send data exactly as it exists on disk. This allows backups to // be taken even if encryption keys are not currently loaded. The backup may then be // received on an untrusted machine since that machine will not have the encryption keys // to read the protected data or alter it without being detected. Upon being received, // the dataset will have the same encryption keys as it did on the send side, although // the keylocation property will be defaulted to prompt if not otherwise provided. For // unencrypted datasets, this flag will be equivalent to -Lec. Note that if you do not // use this flag for sending encrypted datasets, data will be sent unencrypted and may be // re-encrypted with a different encryption key on the receiving system, which will // disable the ability to do a raw send to that system for incrementals. Raw bool // Include the dataset's properties in the stream. This flag is implicit when -R is // specified. The receiving system must also support this feature. Sends of encrypted // datasets must use -w when using this flag. IncludeProperties bool // Generate an incremental stream from the first snapshot (the incremental source) to the // second snapshot (the incremental target). The incremental source can be specified as // the last component of the snapshot name (the @ character and following) and it is // assumed to be from the same file system as the incremental target. // // If the destination is a clone, the source may be the origin snapshot, which must be // fully specified (for example, pool/fs@origin, not just @origin). IncrementalBase *Dataset // When set, uses a rate-limiter to limit the flow to this amount of bytes per second BytesPerSecond int64 // CompressionLevel is the level of zstd compression, 0 for off CompressionLevel zstd.EncoderLevel }
SendOptions are options you can specify to customize the send command
type SnapshotOptions ¶
type SnapshotOptions struct { // Sets the specified properties on the snapshot. Properties map[string]string // Recursively create snapshots of all descendent datasets. Recursive bool }
SnapshotOptions are options you can specify to customize the snapshot command
type UnloadKeyOptions ¶
type UnloadKeyOptions struct { // Recursively loads the keys for the specified filesystem and all descendent encryption roots. Recursive bool }
UnloadKeyOptions are options you can specify to customize the unload-key command
type UnmountOptions ¶
type UnmountOptions struct { // Forcefully unmount the file system, even if it is currently in use. Force bool // Unload keys for any encryption roots unmounted by this command. UnloadKeys bool }
UnmountOptions are options you can specify to customize the unmount command