zfs

package module
v3.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 23, 2023 License: Apache-2.0 Imports: 10 Imported by: 50

README

Go Wrapper for ZFS

Simple wrappers for ZFS command line tools.

GoDoc

Requirements

You need a working ZFS setup. To use on Ubuntu 14.04, setup ZFS:

sudo apt-get install python-software-properties
sudo apt-add-repository ppa:zfs-native/stable
sudo apt-get update
sudo apt-get install ubuntu-zfs libzfs-dev

Developed using Go 1.3, but currently there isn't anything 1.3 specific. Don't use Ubuntu packages for Go, use http://golang.org/doc/install

Generally you need root privileges to use anything zfs related.

Status

This has been only been tested on Ubuntu 14.04

In the future, we hope to work directly with libzfs.

Hacking

The tests have decent examples for most functions.

//assuming a zpool named test
//error handling omitted


f, err := zfs.CreateFilesystem("test/snapshot-test", nil)
ok(t, err)

s, err := f.Snapshot("test", nil)
ok(t, err)

// snapshot is named "test/snapshot-test@test"

c, err := s.Clone("test/clone-test", nil)

err := c.Destroy()
err := s.Destroy()
err := f.Destroy()

Contributing

See the contributing guidelines

Documentation

Overview

Package zfs provides wrappers around the ZFS command line tools.

Index

Constants

View Source 
const (
	DatasetFilesystem = "filesystem"
	DatasetSnapshot   = "snapshot"
	DatasetVolume     = "volume"
)

ZFS dataset types, which can indicate if a dataset is a filesystem, snapshot, or volume.

View Source 
const (
	DestroyDefault         DestroyFlag = 1 << iota
	DestroyRecursive                   = 1 << iota
	DestroyRecursiveClones             = 1 << iota
	DestroyDeferDeletion               = 1 << iota
	DestroyForceUmount                 = 1 << iota
)

Valid destroy options.

View Source 
const (
	ZpoolOnline   = "ONLINE"
	ZpoolDegraded = "DEGRADED"
	ZpoolFaulted  = "FAULTED"
	ZpoolOffline  = "OFFLINE"
	ZpoolUnavail  = "UNAVAIL"
	ZpoolRemoved  = "REMOVED"
)

ZFS zpool states, which can indicate if a pool is online, offline, degraded, etc.

More information regarding zpool states can be found in the ZFS manual: https://openzfs.github.io/openzfs-docs/man/7/zpoolconcepts.7.html#Device_Failure_and_Recovery

Variables

This section is empty.

Functions

func SetLogger 

func SetLogger(l Logger)

SetLogger set a log handler to log all commands including arguments before they are executed.

Types

type ChangeType 

type ChangeType int

ChangeType is the type of inode change as reported by Diff. 

const (
	Removed ChangeType = iota
	Created
	Modified
	Renamed
)

Types of Changes.

type Dataset 

type Dataset struct {
	Name          string
	Origin        string
	Used          uint64
	Avail         uint64
	Mountpoint    string
	Compression   string
	Type          string
	Written       uint64
	Volsize       uint64
	Logicalused   uint64
	Usedbydataset uint64
	Quota         uint64
	Referenced    uint64
}

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(name string, properties map[string]string) (*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(name string, size uint64, properties map[string]string) (*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 Datasets 

func Datasets(filter string) ([]*Dataset, error)

Datasets returns a slice of ZFS datasets, regardless of type. A filter argument may be passed to select a dataset with the matching name, or empty string ("") may be used to select all datasets.

func Filesystems 

func Filesystems(filter string) ([]*Dataset, error)

Filesystems 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 GetDataset 

func GetDataset(name string) (*Dataset, error)

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 ReceiveSnapshot 

func ReceiveSnapshot(input io.Reader, name string) (*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 Snapshots 

func Snapshots(filter string) ([]*Dataset, error)

Snapshots 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 Volumes 

func Volumes(filter string) ([]*Dataset, error)

Volumes 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 (*Dataset) Children 

func (d *Dataset) Children(depth uint64) ([]*Dataset, error)

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 

func (d *Dataset) Clone(dest string, properties map[string]string) (*Dataset, error)

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(flags DestroyFlag) 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) Diff 

func (d *Dataset) Diff(snapshot string) ([]*InodeChange, error)

Diff returns changes between a snapshot and the given ZFS dataset. The snapshot name must include the filesystem part as it is possible to compare clones with their origin snapshots.

func (*Dataset) GetProperty 

func (d *Dataset) GetProperty(key string) (string, error)

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) IncrementalSend 

func (d *Dataset) IncrementalSend(baseSnapshot *Dataset, output io.Writer) error

IncrementalSend sends a ZFS stream of a snapshot to the input io.Writer using the baseSnapshot as the starting point. An error will be returned if the input dataset is not of snapshot type.

func (*Dataset) Mount 

func (d *Dataset) Mount(overlay bool, options []string) (*Dataset, error)

Mount mounts ZFS file systems.

func (*Dataset) Rename 

func (d *Dataset) Rename(name string, createParent, recursiveRenameSnapshots bool) (*Dataset, error)

Rename renames a dataset.

func (*Dataset) Rollback 

func (d *Dataset) Rollback(destroyMoreRecent bool) error

Rollback rolls back the receiving ZFS dataset to a previous snapshot. Optionally, intermediate snapshots can be destroyed. A ZFS snapshot rollback cannot be completed without this option, if more recent snapshots exist. An error will be returned if the input dataset is not of snapshot type.

func (*Dataset) SendSnapshot 

func (d *Dataset) SendSnapshot(output io.Writer) error

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 

func (d *Dataset) SetProperty(key, val string) error

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(name string, recursive bool) (*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) Snapshots 

func (d *Dataset) Snapshots() ([]*Dataset, error)

Snapshots returns a slice of all ZFS snapshots of a given dataset.

func (*Dataset) Unmount 

func (d *Dataset) Unmount(force bool) (*Dataset, error)

Unmount unmounts currently mounted ZFS file systems.

type DestroyFlag 

type DestroyFlag int

DestroyFlag is the options flag passed to Destroy.

type Error 

type Error struct {
	Err    error
	Debug  string
	Stderr string
}

Error is an error which is returned when the `zfs` or `zpool` shell commands return with a non-zero exit code.

func (Error) Error 

func (e Error) Error() string

Error returns the string representation of an Error.

type InodeChange 

type InodeChange struct {
	Change               ChangeType
	Type                 InodeType
	Path                 string
	NewPath              string
	ReferenceCountChange int
}

InodeChange represents a change as reported by Diff.

type InodeType 

type InodeType int

InodeType is the type of inode as reported by Diff. 

const (
	BlockDevice InodeType = iota
	CharacterDevice
	Directory
	Door
	NamedPipe
	SymbolicLink
	EventPort
	Socket
	File
)

Types of Inodes.

type Logger 

type Logger interface {
	Log(cmd []string)
}

Logger can be used to log commands/actions.

type Zpool 

type Zpool struct {
	Name          string
	Health        string
	Allocated     uint64
	Size          uint64
	Free          uint64
	Fragmentation uint64
	ReadOnly      bool
	Freeing       uint64
	Leaked        uint64
	DedupRatio    float64
}

Zpool is a ZFS zpool. A pool is a top-level structure in ZFS, and can contain many descendent datasets.

func CreateZpool 

func CreateZpool(name string, properties map[string]string, args ...string) (*Zpool, error)

CreateZpool creates a new ZFS zpool with the specified name, properties, and optional arguments.

A full list of available ZFS properties and command-line arguments may be found in the ZFS manual: https://openzfs.github.io/openzfs-docs/man/7/zfsprops.7.html. https://openzfs.github.io/openzfs-docs/man/8/zpool-create.8.html

func GetZpool 

func GetZpool(name string) (*Zpool, error)

GetZpool retrieves a single ZFS zpool by name.

func ListZpools 

func ListZpools() ([]*Zpool, error)

ListZpools list all ZFS zpools accessible on the current system.

func (*Zpool) Datasets 

func (z *Zpool) Datasets() ([]*Dataset, error)

Datasets returns a slice of all ZFS datasets in a zpool.

func (*Zpool) Destroy 

func (z *Zpool) Destroy() error

Destroy destroys a ZFS zpool by name.

func (*Zpool) Snapshots 

func (z *Zpool) Snapshots() ([]*Dataset, error)

Snapshots returns a slice of all ZFS snapshots in a zpool.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.