config

Documentation

Overview

Package config describes configuration settings for the snapback tool.

Index

• Constants
• type Backup
• type BackupPath
• type Config
  • func Parse(r io.Reader) (*Config, error)
  • func (c *Config) FindExpired(arch []tarsnap.Archive, now time.Time) []tarsnap.Archive
  • func (c *Config) FindPath(path string) []BackupPath
  • func (c *Config) FindSet(name string) *Backup
  • func (c *Config) List() (tarsnap.Archives, error)
  • func (c *Config) ShouldAutoPrune() bool
  • func (c *Config) UpdatePruneTimestamp() error
• type Interval
  • func (iv *Interval) UnmarshalYAML(unmarshal func(interface{}) error) error
• type ListCache
  • func (c *ListCache) LoadFrom(path string) error
  • func (c *ListCache) SaveTo(path string) error
• type Policy
  • func (p *Policy) Less(q *Policy) bool
  • func (p *Policy) String() string
• type Sampling
  • func (s *Sampling) String() string
  • func (s *Sampling) UnmarshalYAML(unmarshal func(interface{}) error) error

Constants

const (
	Second Interval = 1
	Hour            = 3600 * Second
	Day             = 24 * Hour
	Week            = 7 * Day
	Month           = Interval(30.4375 * float64(Day))
	Year            = Interval(365.25 * float64(Day))
)

Constants for interval notation.

Types

type Backup

type Backup struct {
	// The name defines the base name of the archive. A timestamp will be
	// appended to this name to obtain the complete name.
	Name string

	// Expiration policies.
	Expiration []*Policy

	// Named expiration policy. If no policy is named, any explicit rules are
	// used and the default rules are ignored. Otherwise any explicit rules are
	// added to the selected policy, which is:
	//
	// If "default", the default rules are used.
	//
	// If "none", an empty policy is used.
	//
	// Any other name uses the rules from that policy.
	Policy string

	// Expand shell globs in included paths.
	GlobIncludes bool `json:"globIncludes" yaml:"glob-includes"`

	// The archive creation options for this backup.
	tarsnap.CreateOptions `yaml:",inline"`
}

A Backup describes a collection of files to be backed up as a unit together.

type BackupPath

type BackupPath struct {
	Relative string
	Backup   *Backup
}

A BackupPath describes a path relative to a particular backup.

type Config

type Config struct {
	// An ordered list of backups to be created.
	Backup []*Backup

	// Default expiration policies.
	Expiration []*Policy

	// Named expiration policy sets.
	Policy map[string][]*Policy

	// Enable verbose logging.
	Verbose bool

	// Cache archive listings in this file.
	ListCache string `json:"listCache" yaml:"list-cache"`

	// Auto-prune settings.
	AutoPrune struct {
		Timestamp string   // timestamp file
		Interval  Interval // 0 means every time
	} `json:"autoPrune" yaml:"auto-prune"`

	// Configuration settings for the tarsnap tool.
	tarsnap.Config `yaml:",inline"`
	// contains filtered or unexported fields
}

A Config contains settings for the snapback tool. This is the top-level message used to parse the config file contents as YAML.

func Parse

func Parse(r io.Reader) (*Config, error)

Parse decodes a *Config from the specified reader.

func (*Config) FindExpired

func (c *Config) FindExpired(arch []tarsnap.Archive, now time.Time) []tarsnap.Archive

FindExpired returns a slice of the archives in arch that are eligible for removal under the expiration policies in effect for c, given that now is the moment denoting the present.

func (*Config) FindPath

func (c *Config) FindPath(path string) []BackupPath

FindPath reports the backups that claim path, or nil if there are none. N.B. Only the current backup set configurations are examined.

func (*Config) FindSet

func (c *Config) FindSet(name string) *Backup

FindSet returns the backup matching name, or nil if none matches.

func (*Config) List

func (c *Config) List() (tarsnap.Archives, error)

List returns a list of the known archives, using a cached copy if one is available and updating the cache if necessary. The resulting slice is ordered nondecreasing by creation time and by name.

func (*Config) ShouldAutoPrune

func (c *Config) ShouldAutoPrune() bool

ShouldAutoPrune reports whether an automatic prune cycle should be run at the current time, according to the auto-prune settings.

func (*Config) UpdatePruneTimestamp

func (c *Config) UpdatePruneTimestamp() error

UpdatePruneTimestamp updates the last-pruned timestamp to the current time.

type Interval

type Interval int64

An Interval represents a time interval in seconds. An Interval can be parsed from a string in the format "d.dd unit" or "d unit", where unit is one of

s, sec, secs         -- seconds
h, hr, hour, hours   -- hours
d, day, days         -- days (defined as 24 hours)
w, wk, week, weeks   -- weeks (defined as 7 days)
m, mo, month, months -- months (defined as 365.25/12=30.4375 days)
y, yr, year, years   -- years (defined as 365.25 days)

The space between the number and the unit is optional. Fractional values are permitted, and results are rounded toward zero.

func (*Interval) UnmarshalYAML

func (iv *Interval) UnmarshalYAML(unmarshal func(interface{}) error) error

UnmarshalYAML decodes an interval from a string in the format accepted by parseInterval.

type ListCache

type ListCache struct {
	Tag      string           `json:"cacheTag"`
	Archives tarsnap.Archives `json:"archiveList"`
}

ListCache contains the data stored in the persistent archive list cache.

func (*ListCache) LoadFrom

func (c *ListCache) LoadFrom(path string) error

LoadFrom populates c from the data stored in the specified file.

func (*ListCache) SaveTo

func (c *ListCache) SaveTo(path string) error

SaveTo updates the specified file with the current list cache data.

type Policy

type Policy struct {
	// The rest of this policy applies to backups created in the inclusive
	// interval between min and max before present. Max == 0 means +∞.
	Min Interval `yaml:"after"`
	Max Interval `yaml:"until"`

	// If positive, keep up to this many of most-recent matching archives.
	Latest int

	// If set, retain the specified number of samples per period within this
	// range. Sample ranges are based on the Unix epoch so that they do not move
	// over time, and the latest-created archive in each window is selected as
	// the candidate for that window.
	Sample *Sampling
}

A Policy specifies a policy for which backups to keep. When given a set of policies, the policy that "best" applies to an archive is the earliest, narrowest span of time between min and max before present, inclusive, that includes the creation time of the archive.

For example suppose X is an archive created 7 days before present, and we have these policies:

P(min=1d, max=10d)
Q(min=4d, max=8d)
R(min=3d, max=6d)

Archive X will be governed by policy Q. R is ineligible because it does not span the creation time of X, and Q is preferable to P because Q is only 4 days wide whereas P is 9 days wide.

A policy with a max value of 0 is assumed to end at time +∞.

func (*Policy) Less

func (p *Policy) Less(q *Policy) bool

Less reports whether p precedes q in canonical order. Policies are ordered by the width of their interval, with ties broken by start time.

func (*Policy) String

func (p *Policy) String() string

String renders the policy in human-readable form.

type Sampling

type Sampling struct {
	N      int      // number of samples per period
	Period Interval // period over which to sample
}

A Sampling denotes a rule for how frequently to sample a sequence.

func (*Sampling) String

func (s *Sampling) String() string

func (*Sampling) UnmarshalYAML

func (s *Sampling) UnmarshalYAML(unmarshal func(interface{}) error) error

UnmarshalYAML decodes a sampling from a string of the form "n/iv". As special cases, "none" is allowed as an alias for 0/iv and "all" as an alias for 1/0.