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
• type Interval
  • func (iv *Interval) UnmarshalYAML(unmarshal func(interface{}) error) 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 (ignored if Expiration is set).
	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

	// Configuration settings for the tarsnap tool.
	tarsnap.Config `yaml:",inline"`
}

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.

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 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.