diskplan

Documentation

Overview

Package diskplan builds per-partition capture plans for whole-disk machine snapshots — on Windows one atomic VSS set spans every disk's eligible volumes; everything else captures raw. Shared by the CLI and the local service so service-mode disk captures get identical VSS + exclusion behavior.

Index

• func BuildCaptureExclusions(cfg config.Config, scanSource, volumeLetter string, totalSize int64, ...) *volume.ExclusionMap
• func BuildDiskMemberPlans(diskArgs []string, layouts []*disklayout.DiskLayout, cfg config.Config, ...) ([][]bmr.MemberPlan, func(), error)
• func CorrelateVolumes(l *disklayout.DiskLayout, vols []vss.VolumeOnDisk) map[int]string
• func DiskNumberOf(arg string) (uint32, bool)
• func MemberExclusionRecord(outcomes []ExclusionOutcome) (paths, warnings []string)
• func StaleCloudTempDirs(bases ...string) []string
• type Exclusion
  • func ParseExclusion(raw string) (Exclusion, error)
  • func (e Exclusion) String() string
• type ExclusionOutcome
  • func ApplyExclusions(scanSource, volumeLetter string, m *volume.ExclusionMap, excls []Exclusion) []ExclusionOutcome
  • func BuildDiskMemberPlansWith(diskArgs []string, layouts []*disklayout.DiskLayout, cfg config.Config, ...) ([][]bmr.MemberPlan, []ExclusionOutcome, func(), error)
  • func (o ExclusionOutcome) Describe() string
  • func (o ExclusionOutcome) Excluded() bool
• type ExclusionStatus

Functions

func BuildCaptureExclusions

func BuildCaptureExclusions(cfg config.Config, scanSource, volumeLetter string, totalSize int64, localPaths ...string) *volume.ExclusionMap

buildCaptureExclusions builds the exclusion map for one volume capture: volatile NTFS files (pagefile.sys & co, plus $LogFile/$UsnJrnl), and the physical ranges of any localPaths (the local repo directory, cloud temp dirs) that live on the captured volume — so a backup never captures its own backend state ("don't back up the backup").

scanSource must be the filesystem the stream is read from: the VSS snapshot device when one exists (extents then match the point-in-time image — see the $LogFile reallocation note at the volume-backup call site), otherwise the input image / live volume.

localPaths on a different volume than volumeLetter are ignored: their extents are offsets on a different device, and excluding them would zero unrelated ranges of the captured stream.

Best-effort by design: on error a warning is printed and the capture proceeds unexcluded. Returns nil when disabled or empty.

func BuildDiskMemberPlans

func BuildDiskMemberPlans(diskArgs []string, layouts []*disklayout.DiskLayout, cfg config.Config, localPaths ...string) ([][]bmr.MemberPlan, func(), error)

buildDiskMemberPlans plans capture for every disk of a machine snapshot. On Windows, eligible NTFS volumes across ALL disks are snapshotted in ONE atomic VSS set — the whole machine is crash-consistent as of a single instant, which matters when data on one disk references another. Everything else is captured raw. The returned cleanup releases the set and readers.

func CorrelateVolumes

func CorrelateVolumes(l *disklayout.DiskLayout, vols []vss.VolumeOnDisk) map[int]string

correlateVolumes maps partition index → snapshot-able volume name by exact extent match (a simple volume's single extent starts at the partition offset). Only NTFS-able Windows types are candidates; ESP/MSR/unknown stay raw. Pure logic — unit-tested without Windows.

func DiskNumberOf

func DiskNumberOf(arg string) (uint32, bool)

DiskNumberOf extracts the physical disk number from a --disk / device-path argument. It is the gate deciding whether BuildDiskMemberPlans correlates the disk's volumes for VSS snapshotting.

func MemberExclusionRecord

func MemberExclusionRecord(outcomes []ExclusionOutcome) (paths, warnings []string)

MemberExclusionRecord is what one captured volume's manifest records from its outcomes: the exclusions that were FOR this volume (its drive — not-on-volume ones belong to another member and are omitted, so a disk member's manifest never claims an exclusion meant for a different drive), and the warning line for each that did not apply.

func StaleCloudTempDirs

func StaleCloudTempDirs(bases ...string) []string

StaleCloudTempDirs returns leftover disknexus-s3-* work dirs from crashed cloud runs. A live run's temp dir is created after the snapshot, so only stale ones can hold pre-snapshot bytes (downloaded index, sidecars, packs) that would otherwise be captured into the image.

bases are the scratch bases to scan — exactly those, and nothing else. The engine does not know where the PRODUCT stages its work (the ambient temp, a DISKNEXUS_TEMP override, <stateDir>/tmp since #315): the caller does, and passes every base scratch can go to, or the #297 exclusion silently stops matching the agent's own crashed runs. The engine reads no environment (internal/arch pins that).

Types

type Exclusion

type Exclusion struct {
	Raw   string // as the operator wrote it
	Drive string // "C:" — upper-cased, no trailing separator
	Rel   string // volume-root-relative, slash-separated, no leading slash: "Users/x/VMs"
}

Exclusion is one parsed operator exclusion.

func ParseExclusion

func ParseExclusion(raw string) (Exclusion, error)

ParseExclusion validates and normalizes one operator exclusion. It is the engine's half of the vocabulary — what a capture can resolve. Policy about which paths are foot-guns (\Windows, a whole users tree) belongs to the product's doors, on top of this.

func (Exclusion) String

func (e Exclusion) String() string

String renders the exclusion in its canonical Windows form.

type ExclusionOutcome

type ExclusionOutcome struct {
	Exclusion Exclusion
	Status    ExclusionStatus
	Bytes     int64  // distinct bytes this exclusion added to the map (applied only)
	Detail    string // filesystem name, or the error, for the non-applied cases
}

ExclusionOutcome reports one exclusion against one captured volume.

func ApplyExclusions

func ApplyExclusions(scanSource, volumeLetter string, m *volume.ExclusionMap, excls []Exclusion) []ExclusionOutcome

ApplyExclusions resolves each exclusion against the volume being captured (scanSource: the VSS snapshot device, live volume, or image; volumeLetter: the drive it is, "C:" — empty when the capture has no letter, e.g. an image file, in which case every exclusion is taken to be for it) and adds the matching extents to m. One outcome per exclusion, in order.

func BuildDiskMemberPlansWith

func BuildDiskMemberPlansWith(diskArgs []string, layouts []*disklayout.DiskLayout, cfg config.Config, excls []Exclusion, localPaths ...string) ([][]bmr.MemberPlan, []ExclusionOutcome, func(), error)

BuildDiskMemberPlansWith is BuildDiskMemberPlans with operator exclusions (#468): each is resolved against every snapshotted member whose drive letter it names, and the outcomes — applied, not found, not NTFS — come back per member for the caller to report and record.

func (ExclusionOutcome) Describe

func (o ExclusionOutcome) Describe() string

Describe is the operator-facing one-liner.

func (ExclusionOutcome) Excluded

func (o ExclusionOutcome) Excluded() bool

Excluded says whether the exclusion's bytes are out of this capture.

type ExclusionStatus

type ExclusionStatus string

ExclusionStatus is what became of one exclusion at capture.

const (
	// ExclusionApplied: the path exists on the captured volume and its
	// blocks are zeroed in this capture.
	ExclusionApplied ExclusionStatus = "applied"
	// ExclusionNotOnVolume: the drive letter is not the captured volume's.
	// Nothing to do here; it may apply to another member of a disk capture.
	ExclusionNotOnVolume ExclusionStatus = "not-on-volume"
	// ExclusionNotFound: the volume is the right one, and the path is not
	// on it. ITS BYTES ARE NOT EXCLUDED — the operator must hear this.
	ExclusionNotFound ExclusionStatus = "not-found"
	// ExclusionUnsupported: the volume is not NTFS; the walk cannot resolve
	// paths there. Not excluded.
	ExclusionUnsupported ExclusionStatus = "unsupported-filesystem"
	// ExclusionFailed: the walk errored. Not excluded.
	ExclusionFailed ExclusionStatus = "failed"
)