zfs

README

Go Wrapper for ZFS

Simple wrappers for ZFS command line tools.

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 ommitted


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
• func SetLogger(l Logger)
• type ChangeType
• type Dataset
  • func CreateFilesystem(name string, properties map[string]string) (*Dataset, error)
  • func CreateVolume(name string, size uint64, properties map[string]string) (*Dataset, error)
  • func Datasets(filter string) ([]*Dataset, error)
  • func Filesystems(filter string) ([]*Dataset, error)
  • func GetDataset(name string) (*Dataset, error)
  • func ReceiveSnapshot(input io.Reader, name string) (*Dataset, error)
  • func Snapshots(filter string) ([]*Dataset, error)
  • func Volumes(filter string) ([]*Dataset, error)
  • func (d *Dataset) Children(depth uint64) ([]*Dataset, error)
  • func (d *Dataset) Clone(dest string, properties map[string]string) (*Dataset, error)
  • func (d *Dataset) Destroy(flags DestroyFlag) error
  • func (d *Dataset) Diff(snapshot string) ([]*InodeChange, error)
  • func (d *Dataset) GetProperty(key string) (string, error)
  • func (d *Dataset) Rollback(destroyMoreRecent bool) error
  • func (d *Dataset) SendSnapshot(output io.Writer) error
  • func (d *Dataset) SetProperty(key, val string) error
  • func (d *Dataset) Snapshot(name string, recursive bool) (*Dataset, error)
  • func (d *Dataset) Snapshots() ([]*Dataset, error)
• type DestroyFlag
• type Error
  • func (e Error) Error() string
• type InodeChange
• type InodeType
• type Logger
• type Zpool
  • func CreateZpool(name string, properties map[string]string, args ...string) (*Zpool, error)
  • func GetZpool(name string) (*Zpool, error)
  • func ListZpools() ([]*Zpool, error)
  • func (z *Zpool) Datasets() ([]*Dataset, error)
  • func (z *Zpool) Destroy() error
  • func (z *Zpool) Snapshots() ([]*Dataset, error)

Constants

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

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

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

Valid destroy options

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 here: https://docs.oracle.com/cd/E19253-01/819-5461/gamno/index.html.

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
	Usedbydataset uint64
	Logicalused   uint64
	Quota         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: http://www.freebsd.org/cgi/man.cgi?zfs(8).

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 here: https://www.freebsd.org/cgi/man.cgi?zfs(8).

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 here: https://www.freebsd.org/cgi/man.cgi?zfs(8).

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, creates a new snapshot 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 here: https://www.freebsd.org/cgi/man.cgi?zfs(8).

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 here: https://www.freebsd.org/cgi/man.cgi?zfs(8).

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.

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
}

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 here: https://www.freebsd.org/cgi/man.cgi?zfs(8).

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.