Documentation
¶
Overview ¶
Package blksnap provides a pure Go interface to the veeamblksnap kernel module for block device snapshot management.
It auto-detects the loaded module version and supports both API generations:
v2 (VAL-13.x): Uses /dev/veeamblksnap + /dev/bdevfilter with path-based device identification. The ioctl protocol aligns with the VAL-13.0/13.0.1 standalone branches.
v1 (VAL-6.x): Uses /dev/veeamblksnap only with major:minor device identification. The ioctl protocol aligns with the VAL-6.x standalone branches.
Auto-detection ¶
The first call to OpenService or OpenTracker probes the system and locks in the API version. No explicit version selection is needed.
Requirements ¶
The veeamblksnap (and for v2, bdevfilter) kernel modules must be loaded. This package targets Linux only (linux/amd64, linux/arm64).
Index ¶
- Constants
- Variables
- func CreateSnapshotV1(devices []DevID) (*Snapshot, UUID, error)
- type APIVersion
- type CBTHandle
- func (c *CBTHandle) Close() error
- func (c *CBTHandle) Data() ([]byte, error)
- func (c *CBTHandle) DataChunked(chunkSize uint32, fn func(offset uint32, data []byte) error) error
- func (c *CBTHandle) ErrorCode() (int32, error)
- func (c *CBTHandle) Image() (string, error)
- func (c *CBTHandle) Info() (CBTInfo, error)
- type CBTInfo
- type DevID
- type ModuleVersion
- type SectorRange
- type Service
- type Session
- type SessionOption
- type Snapshot
- type SnapshotEvent
- type SnapshotEventCode
- type SnapshotEventCorrupted
- type SnapshotEventLowFreeSpace
- type SnapshotImageInfo
- type Tracker
- func (t *Tracker) Attach() (bool, error)
- func (t *Tracker) CBTInfo() (CBTInfo, error)
- func (t *Tracker) Close() error
- func (t *Tracker) Detach() error
- func (t *Tracker) MarkDirty(ranges []SectorRange) error
- func (t *Tracker) ReadCBTMap(offset, length uint32, dst []byte) error
- func (t *Tracker) SnapshotAdd(id UUID) error
- func (t *Tracker) SnapshotInfo() (SnapshotImageInfo, error)
- func (t *Tracker) V1DevID() DevID
- type UUID
Examples ¶
Constants ¶
const ( V1ImagePrefix = "veeamblksnapimg" // VAL-6.x V2ImagePrefix = "vbsnap" // VAL-13.x )
Image prefixes used by the kernel module for snapshot image device names.
const ControlDevice = "/dev/veeamblksnap"
ControlDevice returns the control device path for snapshot management.
const FilterDevice = "/dev/bdevfilter"
FilterDevice is the bdevfilter path (v2 only).
Variables ¶
var ( ErrNotFound = errors.New("blksnap: not found") ErrAlreadyExists = errors.New("blksnap: already exists") ErrInterrupted = errors.New("blksnap: interrupted") ErrNoData = errors.New("blksnap: no data available") ErrNoSpace = errors.New("blksnap: no space left on device") ErrCorrupted = errors.New("blksnap: snapshot corrupted") )
Functions ¶
Types ¶
type APIVersion ¶
type APIVersion int
APIVersion identifies the kernel module API generation.
const ( // APIV1 is the VAL-6.x API. All operations use /dev/veeamblksnap only, // devices are identified by major:minor numbers, and the snapshot create // ioctl takes a device array directly. APIV1 APIVersion = 1 // APIV2 is the VAL-13.x API. Snapshot control uses /dev/veeamblksnap, // block device filter operations use /dev/bdevfilter, and devices are // identified by filesystem path. APIV2 APIVersion = 2 )
func Detect ¶
func Detect() (APIVersion, error)
Detect probes the system to determine which API version the loaded kernel module supports. It opens the control device and checks whether /dev/bdevfilter exists (v2) or not (v1). The result is cached.
func Detected ¶
func Detected() APIVersion
Detected returns the detected API version. It calls Detect internally.
type CBTHandle ¶
type CBTHandle struct {
// contains filtered or unexported fields
}
CBTHandle provides a high-level interface to Change Block Tracking on a block device that has the blksnap filter attached (v2) or is tracked (v1).
func (*CBTHandle) DataChunked ¶
DataChunked reads the full CBT bitmap in chunks.
type CBTInfo ¶
type CBTInfo struct {
DeviceCapacity uint64
BlockSize uint32
BlockCount uint32
GenerationID UUID
ChangesNumber uint8
}
CBTInfo holds change block tracking metadata for a block device.
type ModuleVersion ¶
ModuleVersion represents the kernel module version.
Example ¶
package main
import (
"fmt"
"github.com/pbs-plus/go-blksnap"
)
func main() {
v := blksnap.ModuleVersion{Major: 1, Minor: 2, Revision: 3, Build: 4}
fmt.Println(v.String())
}
Output: 1.2.3.4
func (ModuleVersion) String ¶
func (v ModuleVersion) String() string
type SectorRange ¶
SectorRange describes a region on a block device in sectors.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service provides low-level access to the blksnap control device.
func OpenService ¶
OpenService opens a connection to the control device and auto-detects the API version.
func (*Service) Version ¶
func (s *Service) Version() (ModuleVersion, error)
Version returns the kernel module version.
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session manages a blksnap snapshot session across one or more block devices.
func CreateSession ¶
func CreateSession(devices []string, diffStoragePath string, limitBytes uint64, opts ...SessionOption) (*Session, error)
CreateSession creates a new blksnap session.
For v2 (VAL-13.x): attaches bdevfilter, creates snapshot with diff storage, adds devices, starts event monitoring, takes snapshot.
For v1 (VAL-6.x): creates snapshot with device IDs, appends diff storage via low_free_space events, starts event monitoring, takes snapshot.
type SessionOption ¶
type SessionOption func(*sessionConfig)
func WithEventTimeout ¶
func WithEventTimeout(d time.Duration) SessionOption
func WithLogger ¶
func WithLogger(logger *slog.Logger) SessionOption
type Snapshot ¶
type Snapshot struct {
// contains filtered or unexported fields
}
Snapshot manages a single blksnap snapshot.
func CreateSnapshot ¶
CreateSnapshot creates a new snapshot with a difference storage file and limit. v2 only — v1 creates snapshots differently (via CreateSnapshotV1).
func OpenSnapshot ¶
OpenSnapshot opens an existing snapshot by UUID.
func (*Snapshot) CollectImages ¶
CollectImages returns the snapshot image info for all devices in the snapshot (v1 only).
type SnapshotEvent ¶
type SnapshotEvent struct {
Code SnapshotEventCode
TimeLabel int64
Corrupted *SnapshotEventCorrupted
NoSpace *SnapshotEventLowFreeSpace
}
SnapshotEvent represents an event received from a held snapshot.
type SnapshotEventCode ¶
type SnapshotEventCode int
SnapshotEventCode identifies the type of snapshot event.
const ( // EventCorrupted — snapshot image corrupted. // v1 kernel code 1, v2 kernel code 0. EventCorrupted SnapshotEventCode = 0 // EventLowFreeSpace — difference storage limit reached (v1) or no space (v2). // v1 kernel code 0, v2 kernel code 1. EventLowFreeSpace SnapshotEventCode = 1 )
type SnapshotEventCorrupted ¶
SnapshotEventCorrupted provides details for EventCorrupted.
type SnapshotEventLowFreeSpace ¶
type SnapshotEventLowFreeSpace struct {
RequestedSectors uint64
}
SnapshotEventLowFreeSpace provides details when the diff storage is full.
type SnapshotImageInfo ¶
SnapshotImageInfo describes the snapshot image for a device (v2 only).
type Tracker ¶
type Tracker struct {
// contains filtered or unexported fields
}
Tracker manages CBT and snapshot participation for a single block device.
func OpenTracker ¶
OpenTracker opens the appropriate device for the detected API version. devicePath is the block device path (e.g., /dev/sda1) — used for v2 directly, stat'd for major:minor in v1.
func (*Tracker) MarkDirty ¶
func (t *Tracker) MarkDirty(ranges []SectorRange) error
func (*Tracker) SnapshotAdd ¶
SnapshotAdd adds the device to a snapshot. v2 only — v1 adds at create time.
func (*Tracker) SnapshotInfo ¶
func (t *Tracker) SnapshotInfo() (SnapshotImageInfo, error)
SnapshotInfo retrieves snapshot image information (v2 only).
type UUID ¶
type UUID [16]byte
UUID is a 16-byte unique identifier used by blksnap for snapshots.
Example ¶
package main
import (
"fmt"
"github.com/pbs-plus/go-blksnap"
)
func main() {
id, err := blksnap.ParseUUID("550e8400-e29b-41d4-a716-446655440000")
if err != nil {
panic(err)
}
fmt.Println(id.String())
}
Output: 550e8400-e29b-41d4-a716-446655440000
func MustParseUUID ¶
Example ¶
package main
import (
"fmt"
"github.com/pbs-plus/go-blksnap"
)
func main() {
id := blksnap.MustParseUUID("550e8400-e29b-41d4-a716-446655440000")
fmt.Println(id.IsZero())
}
Output: false