dockerbackup

package
v1.0.2 Latest Latest
Warning

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

 Go to latest Published: Oct 26, 2026 License: AGPL-3.0 Imports: 15 Imported by: 0

Documentation

Overview

Package dockerbackup holds the Docker host backup job specification, the agent-side settings and the run manifest. It is shared by the server (validation) and the filesystem agent (execution on the Docker host), so it must stay free of process-execution dependencies.

Index

Constants

View Source 
const (
	// VolumeAccessAuto reads volumes directly when their mountpoint is visible to
	// the agent and falls back to helper containers otherwise
	VolumeAccessAuto = "auto"
	// VolumeAccessDirect reads /var/lib/docker/volumes/<name>/_data from the host filesystem
	VolumeAccessDirect = "direct"
	// VolumeAccessHelper streams every volume through a throwaway container
	VolumeAccessHelper = "helper"
)

Volume access modes (agent setting docker_backup.volume_access)

View Source 
const (
	// ArchiveName is the pxar archive holding the definitions and the volumes
	ArchiveName = "docker"
	// ManifestBlobName / ManifestFileName is the run manifest (blob and inside collect/)
	ManifestBlobName = "fallbck-docker.json"
	ManifestFileName = "fallbck-docker.json"
	// RestoreScriptName is the generated restore runbook inside collect/
	RestoreScriptName = "fallbck-docker-restore.sh"
	// CollectEntry is the archive entry holding definitions, compose files, the
	// daemon configuration, saved images, the manifest and the restore script
	CollectEntry = "collect"
	// VolumeEntryPrefix prefixes the archive entry of every named volume
	VolumeEntryPrefix = "vol-"
	// HostPathEntryPrefix prefixes the archive entry of every additional host path
	// (/srv/app → host-srv-app)
	HostPathEntryPrefix = "host-"
)

Names inside the snapshot

View Source 
const (
	// LabelSkip excludes a container (its definition) or a volume from the backup
	LabelSkip = "fallbck.io/skip"
	// LabelPause pauses a container while the volumes it mounts are read
	LabelPause = "fallbck.io/pause"
)

Labels honoured on containers and volumes

View Source 
const (
	// ImagesRefs records image references (name, tag, digest) only
	ImagesRefs = "refs"
	// ImagesLocal additionally saves images without a registry reference (built locally)
	ImagesLocal = "local"
	// ImagesAll saves every image a container uses
	ImagesAll = "all"
)

Image modes

View Source 
const DefaultHelperImage = "alpine:3.24"

DefaultHelperImage mounts volumes and host directories for helper-mode reads

View Source 
const DefaultMinFreeBytes = int64(1 << 30)

DefaultMinFreeBytes is the free space a Docker run leaves on the spool filesystem

View Source 
const DefaultSocket = "/var/run/docker.sock"

DefaultSocket is the Docker daemon socket unless DOCKER_HOST names another one

View Source 
const ManifestSchemaVersion = 1

ManifestSchemaVersion is bumped on incompatible manifest changes

Variables

View Source 
var ErrInvalidSpec = errors.New("invalid Docker host job configuration")

ErrInvalidSpec wraps every validation failure

Functions

func HostPathEntry added in v0.11.0 

func HostPathEntry(p string) string

HostPathEntry is the archive entry name of a host path (/srv/app → host-srv-app)

func IsDockerHost 

func IsDockerHost(socket string) bool

IsDockerHost reports whether a Docker daemon answers on the socket (empty: the default socket). It is called from enrollment and every heartbeat, so it is cheap: a stat, then one /_ping with a short timeout (a socket the agent may not open fails the ping and counts as absent).

func MatchesAny 

func MatchesAny(name string, globs []string) bool

MatchesAny reports whether name matches one of the globs (container names are matched with and without their leading slash)

func NormalizeImages 

func NormalizeImages(mode string) (string, bool)

NormalizeImages maps "" to refs and reports unknown modes

func Ping 

func Ping(ctx context.Context, socket string) error

Ping performs GET /_ping over the unix socket

func SocketPath 

func SocketPath() string

SocketPath is the daemon socket: DOCKER_HOST when it names a unix socket, else the default. TCP daemons are not supported (the agent runs on the host it backs up).

func SocketTransport 

func SocketTransport(socket string) *http.Transport

SocketTransport dials the unix socket for every request

Types

type ArchiveEntry 

type ArchiveEntry struct {
	Name   string `json:"name"`
	Source string `json:"source"`
	// Kind: collect | volume | host
	Kind string `json:"kind"`
}

ArchiveEntry maps a top-level archive name to its origin

type BindMount 

type BindMount struct {
	Source     string   `json:"source"`
	Containers []string `json:"containers"`
}

BindMount is a host directory mounted into containers

type Collected 

type Collected struct {
	Name     string `json:"name"`
	Endpoint string `json:"endpoint,omitempty"`
	File     string `json:"file,omitempty"`
	Error    string `json:"error,omitempty"`
}

Collected is the outcome of one collector

type ComposeFile 

type ComposeFile struct {
	// File is the path inside collect/ (compose/<project>/<name>)
	File string `json:"file"`
	// Source is the absolute host path it was read from (where a restore puts it back)
	Source string `json:"source"`
}

ComposeFile is one compose config or env file stored inside collect/

type ComposeProject 

type ComposeProject struct {
	Name        string        `json:"name"`
	WorkingDir  string        `json:"working_dir,omitempty"`
	ConfigFiles []string      `json:"config_files,omitempty"`
	Archived    []ComposeFile `json:"archived,omitempty"`
	Services    []string      `json:"services,omitempty"`
}

ComposeProject groups the containers of one compose project

type Config 

type Config struct {
	// VolumeAccess is auto (default), direct or helper
	VolumeAccess string `yaml:"volume_access,omitempty" json:"volume_access,omitempty"`
	// HelperImage is the image of the throwaway containers used in helper mode
	HelperImage string `yaml:"helper_image,omitempty" json:"helper_image,omitempty"`
	// Socket is the daemon's unix socket (default: DOCKER_HOST if unix://, else /var/run/docker.sock)
	Socket string `yaml:"socket,omitempty" json:"socket,omitempty"`
	// MinFreeBytes must stay free on the spool filesystem while images are saved and
	// volumes are copied into it (default 1 GiB): a run never fills the host's disk
	MinFreeBytes int64 `yaml:"min_free_bytes,omitempty" json:"min_free_bytes,omitempty"`
}

Config is the agent-side Docker settings block (agent.yaml docker_backup:, env FALLBCK_AGENT_DOCKER_*)

func (*Config) EffHelperImage 

func (c *Config) EffHelperImage() string

func (*Config) EffMinFreeBytes added in v1.0.0 

func (c *Config) EffMinFreeBytes() int64

EffMinFreeBytes applies the default

func (*Config) EffSocket 

func (c *Config) EffSocket() string

func (*Config) EffVolumeAccess 

func (c *Config) EffVolumeAccess() string

EffVolumeAccess / EffHelperImage / EffSocket apply the defaults

func (*Config) Validate 

func (c *Config) Validate() error

Validate checks the volume access mode

type Container 

type Container struct {
	Name        string            `json:"name"`
	ID          string            `json:"id"`
	Image       string            `json:"image"`
	ImageID     string            `json:"image_id,omitempty"`
	ImageDigest string            `json:"image_digest,omitempty"`
	State       string            `json:"state"` // running | exited | paused | created | ...
	Status      string            `json:"status,omitempty"`
	Created     string            `json:"created,omitempty"`
	Project     string            `json:"compose_project,omitempty"`
	Service     string            `json:"compose_service,omitempty"`
	WorkingDir  string            `json:"compose_working_dir,omitempty"`
	Networks    []string          `json:"networks,omitempty"`
	Mounts      []Mount           `json:"mounts,omitempty"`
	Ports       []Port            `json:"ports,omitempty"`
	Restart     string            `json:"restart_policy,omitempty"`
	Labels      map[string]string `json:"labels,omitempty"`
	Paused      bool              `json:"paused_for_backup,omitempty"`
	Skipped     string            `json:"skipped,omitempty"`    // reason, when the definition was not captured
	Definition  string            `json:"definition,omitempty"` // inspect JSON inside collect/
}

Container is one container whose definition was captured

type DaemonInfo 

type DaemonInfo struct {
	ConfigPath string `json:"config_path,omitempty"`
	Archived   bool   `json:"archived"`
}

DaemonInfo records the daemon configuration file

type HostInfo 

type HostInfo struct {
	Hostname          string `json:"hostname"`
	DockerVersion     string `json:"docker_version,omitempty"`
	APIVersion        string `json:"api_version,omitempty"`
	OS                string `json:"os,omitempty"` // OperatingSystem from /info
	OSType            string `json:"os_type,omitempty"`
	Arch              string `json:"arch,omitempty"`
	Kernel            string `json:"kernel,omitempty"`
	RootDir           string `json:"root_dir,omitempty"`
	StorageDriver     string `json:"storage_driver,omitempty"`
	Swarm             string `json:"swarm,omitempty"` // inactive | active | pending | ...
	SwarmManager      bool   `json:"swarm_manager,omitempty"`
	Rootless          bool   `json:"rootless,omitempty"`
	Containers        int    `json:"containers"`
	ContainersRunning int    `json:"containers_running"`
	ImageCount        int    `json:"image_count"`
	// VolumeAccess is the mode the run used: direct | helper | mixed
	VolumeAccess string `json:"volume_access,omitempty"`
}

HostInfo describes the Docker host and daemon

type HostPath added in v0.11.0 

type HostPath struct {
	Path    string `json:"path"`
	Entry   string `json:"entry,omitempty"`  // archive entry (host-<path>)
	Access  string `json:"access,omitempty"` // direct | helper
	Skipped string `json:"skipped,omitempty"`
}

HostPath is one additional host directory of the job

type Image 

type Image struct {
	ID          string   `json:"id"`
	RepoTags    []string `json:"repo_tags,omitempty"`
	RepoDigests []string `json:"repo_digests,omitempty"`
	SizeBytes   int64    `json:"size_bytes,omitempty"`
	Local       bool     `json:"local,omitempty"` // no registry reference
	Saved       string   `json:"saved,omitempty"` // tarball inside collect/images/
	UsedBy      []string `json:"used_by,omitempty"`
}

Image is one image in use by a container

type Manifest 

type Manifest struct {
	SchemaVersion int               `json:"schema_version"`
	Generator     ManifestGenerator `json:"generator"`
	Job           ManifestJob       `json:"job"`
	Snapshot      ManifestSnapshot  `json:"snapshot"`
	StartedAt     time.Time         `json:"started_at"`
	FinishedAt    time.Time         `json:"finished_at"`
	Host          HostInfo          `json:"host"`
	Containers    []Container       `json:"containers"`
	Volumes       []Volume          `json:"volumes"`
	Networks      []Network         `json:"networks"`
	Images        []Image           `json:"images"`
	Compose       []ComposeProject  `json:"compose_projects"`
	Daemon        DaemonInfo        `json:"daemon"`
	// HostPaths are the job's additional host directories and how they were archived
	HostPaths []HostPath `json:"host_paths,omitempty"`
	// BindMounts lists host directories mounted into containers; they are recorded
	// for the operator but not archived unless listed as a host path
	BindMounts []BindMount `json:"bind_mounts,omitempty"`
	// Entries maps archive top-level names to their source
	Entries  []ArchiveEntry `json:"entries"`
	Excludes []string       `json:"excludes,omitempty"`
	// Collected records every collector that ran (and how it went)
	Collected []Collected `json:"collected"`
	Spec      *Spec       `json:"spec,omitempty"`
	Warnings  []string    `json:"warnings,omitempty"`
	Restore   Restore     `json:"restore"`
}

Manifest describes one Docker host backup: what was collected, how the archive is laid out and how to restore it. It is stored as fallbck-docker.json inside the collect/ entry and as a blob next to the archive.

func ParseManifest 

func ParseManifest(data []byte) (*Manifest, error)

ParseManifest decodes a manifest

func (*Manifest) Marshal 

func (m *Manifest) Marshal() ([]byte, error)

Marshal renders the manifest as indented JSON

type ManifestGenerator 

type ManifestGenerator struct {
	Agent    string `json:"agent"`
	Version  string `json:"version"`
	Hostname string `json:"hostname"`
}

ManifestGenerator identifies the agent that produced the backup

type ManifestJob 

type ManifestJob struct {
	ID          string `json:"id"`
	Name        string `json:"name,omitempty"`
	RunID       string `json:"run_id"`
	BackupRunID string `json:"backup_run_id"`
}

ManifestJob identifies the job and run

type ManifestSnapshot 

type ManifestSnapshot struct {
	Type    string    `json:"type"`
	ID      string    `json:"id"`
	Time    time.Time `json:"time"`
	Archive string    `json:"archive"`
}

ManifestSnapshot is the PBS snapshot identity

type Mount 

type Mount struct {
	Type        string `json:"type"` // volume | bind | tmpfs | npipe
	Source      string `json:"source,omitempty"`
	Destination string `json:"destination"`
	Volume      string `json:"volume,omitempty"`
	RW          bool   `json:"rw"`
}

Mount is one mount of a container

type Network 

type Network struct {
	Name       string            `json:"name"`
	ID         string            `json:"id"`
	Driver     string            `json:"driver"`
	Scope      string            `json:"scope,omitempty"`
	Internal   bool              `json:"internal,omitempty"`
	Attachable bool              `json:"attachable,omitempty"`
	IPv6       bool              `json:"ipv6,omitempty"`
	Subnets    []Subnet          `json:"subnets,omitempty"`
	Options    map[string]string `json:"options,omitempty"`
	Labels     map[string]string `json:"labels,omitempty"`
	Builtin    bool              `json:"builtin,omitempty"` // bridge, host, none: never recreated
	Containers []string          `json:"containers,omitempty"`
	Definition string            `json:"definition,omitempty"`
}

Network is one user-defined (or built-in) network

type Port 

type Port struct {
	HostIP        string `json:"host_ip,omitempty"`
	HostPort      string `json:"host_port"`
	ContainerPort string `json:"container_port"`
	Protocol      string `json:"protocol"`
}

Port is one published port

type Restore 

type Restore struct {
	Summary  string   `json:"summary"`
	Commands []string `json:"commands"`
	Script   string   `json:"script,omitempty"`
}

Restore carries the runbook: a summary, the commands to run, and the script's location inside the archive

type Spec 

type Spec struct {
	// ExcludeContainers are name globs of containers whose definitions are skipped
	ExcludeContainers []string `json:"exclude_containers,omitempty"`
	// ExcludeVolumes are name globs of volumes that are not archived
	ExcludeVolumes []string `json:"exclude_volumes,omitempty"`
	// IncludeUnusedVolumes archives volumes no container mounts (default true)
	IncludeUnusedVolumes *bool `json:"include_unused_volumes,omitempty"`
	// IncludeStopped records the definitions of stopped containers (default true)
	IncludeStopped *bool `json:"include_stopped,omitempty"`
	// Images is refs (default), local or all
	Images string `json:"images,omitempty"`
	// PauseContainers are name globs of containers paused while their volumes are
	// read, in addition to those labeled fallbck.io/pause=true
	PauseContainers []string `json:"pause_containers,omitempty"`
	// HostPaths are additional host directories archived file by file next to the
	// volumes (compose project directories, bind-mounted data, /etc/docker extras),
	// each as its own entry host-<path>
	HostPaths []string `json:"host_paths,omitempty"`
	// ExcludePaths are proxmox-backup-client style patterns against archive paths
	// (/vol-<name>/..., /host-<path>/...)
	ExcludePaths []string `json:"exclude_paths,omitempty"`
}

Spec is the Docker host job configuration (backup_jobs.docker_config). Container, network and volume definitions, compose config files and the daemon configuration are always included; every named volume is archived file by file unless excluded.

func (*Spec) Clone 

func (s *Spec) Clone() *Spec

Clone returns a deep copy

func (*Spec) EffImages 

func (s *Spec) EffImages() string

func (*Spec) EffIncludeStopped 

func (s *Spec) EffIncludeStopped() bool

func (*Spec) EffIncludeUnusedVolumes 

func (s *Spec) EffIncludeUnusedVolumes() bool

EffIncludeUnusedVolumes / EffIncludeStopped / EffImages apply the defaults

func (*Spec) Summary 

func (s *Spec) Summary() string

Summary is a short human-readable description (UI tables, logs)

func (*Spec) Validate 

func (s *Spec) Validate() error

Validate normalises the globs and patterns and checks the image mode

type StatusError 

type StatusError struct {
	Status  int
	Message string
}

StatusError is a non-2xx daemon answer

func (*StatusError) Error 

func (e *StatusError) Error() string

type Subnet 

type Subnet struct {
	Subnet  string `json:"subnet,omitempty"`
	Gateway string `json:"gateway,omitempty"`
	IPRange string `json:"ip_range,omitempty"`
}

Subnet is one IPAM configuration of a network

type Volume 

type Volume struct {
	Name       string            `json:"name"`
	Driver     string            `json:"driver"`
	Mountpoint string            `json:"mountpoint,omitempty"`
	Scope      string            `json:"scope,omitempty"`
	Labels     map[string]string `json:"labels,omitempty"`
	Options    map[string]string `json:"options,omitempty"`
	UsedBy     []string          `json:"used_by,omitempty"`
	Entry      string            `json:"entry,omitempty"`  // archive entry (vol-<name>)
	Access     string            `json:"access,omitempty"` // direct | helper
	Skipped    string            `json:"skipped,omitempty"`
	Paused     []string          `json:"paused_containers,omitempty"`
	Definition string            `json:"definition,omitempty"`
}

Volume is one named volume

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.