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
• 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(recursive bool) 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 Error
  • func (e Error) Error() string
• 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 (
	Byte  = 1
	KByte = Byte * 1024
	MByte = KByte * 1024
	GByte = MByte * 1024
	TByte = GByte * 1024
	PByte = TByte * 1024
	EByte = PByte * 1024
)

based on https://github.com/dustin/go-humanize/blob/master/bytes.go

Types

type Dataset

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

Dataset is a zfs dataset. This could be a volume, filesystem, snapshot. Check the type field 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 filesystem

func CreateVolume

func CreateVolume(name string, size uint64, properties map[string]string) (*Dataset, error)

CreateVolume creates a new volume

func Datasets

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

Datasets returns a slice of all datasets

func Filesystems

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

Filesystems returns a slice of all filesystems

func GetDataset

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

GetDataset retrieves a single dataset

func ReceiveSnapshot

func ReceiveSnapshot(input io.Reader, name string) (*Dataset, error)

ReceiveSnapshot receives a zfs stream into a new snapshot

func Snapshots

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

Snapshots returns a slice of all snapshots

func Volumes

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

Volumes returns a slice of all volumes

func (*Dataset) Children

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

Children returns the children of the dataset. Depth of 0 does not limit recursion.

func (*Dataset) Clone

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

Clone clones a snapshot. An error will be returned if a non-snapshot is used

func (*Dataset) Destroy

func (d *Dataset) Destroy(recursive bool) error

Destroy destroys a dataset

func (*Dataset) GetProperty

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

GetProperty Gets a property

func (*Dataset) Rollback

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

Rollback rolls back a given dataset to a previous snapshot

func (*Dataset) SendSnapshot

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

SendSnapshot sends a snapshot as a zfs stream

func (*Dataset) SetProperty

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

SetProperty sets a property

func (*Dataset) Snapshot

func (d *Dataset) Snapshot(name string, recursive bool) (*Dataset, error)

Snapshot creates a snapshot

func (*Dataset) Snapshots

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

Snapshots returns a slice of all snapshots of a given dataset

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 Zpool

type Zpool struct {
	Name      string
	Health    string
	Allocated uint64
	Size      uint64
	Free      uint64
}

Zpool represents a ZFS Pool

func CreateZpool

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

CreateZpool creates a new zpool

func GetZpool

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

GetZpool retrieves a Zpool

func ListZpools

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

ListZpools list all zpools

func (*Zpool) Datasets

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

Datasets returns a slice of all datasets in a zpool

func (*Zpool) Destroy

func (z *Zpool) Destroy() error

Destroy destroys a zpool

func (*Zpool) Snapshots

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

Snapshots returns a slice of all snapshots in a zpool