Documentation
¶
Overview ¶
Package backup makes a ZIP of a server's data and metadata, and puts one back. An archive is treated as hostile the whole way through, even one this server made: it may have been changed since, or come from someone else.
Making one needs nothing stopped: the database is copied with VACUUM INTO. Bringing one back happens in two steps, as with a reset: it's checked and unpacked beside the data while the server runs, and the swap is made as the server next starts, before anything has these files open. What was there before is moved aside first, and is moved back if anything goes wrong.
Code is never part of a backup. Modules, game cores and helpers come from their signed releases, so an archive can't put a program on this machine.
Index ¶
- Constants
- Variables
- func AskUndo(f Folders, name string) error
- func Cancel(f Folders) (bool, error)
- func CleanParts(ids []string) ([]string, error)
- func CountUploads(f Folders, prefix string) int
- func DefaultParts() []string
- func Delete(f Folders, name string) error
- func Interrupted(f Folders) string
- func IsWrongPassword(err error) bool
- func Prune(f Folders, keep int) (removed []string)
- func Refused(file, reason string) error
- func ValidName(name string) bool
- type AccountInfo
- type CryptHeader
- type FileEntry
- type Folders
- type Info
- type Inspection
- type Key
- type LibraryInfo
- type Manifest
- type Options
- type Part
- type PartContent
- type PartSize
- type PartSummary
- type Refusal
- type Request
- type Result
- type SafetyCopy
- type StageOptions
- type Step
Constants ¶
const ( ManifestName = "manifest.json" ReadmeName = "README.txt" PayloadName = "payload.wmsenc" // the whole inner archive, when protected with a password )
File names inside an archive.
const ( PartLibrary = "library" PartSettings = "settings" PartUsers = "users" PartHistory = "history" PartChannels = "channels" PartArtwork = "artwork" PartModules = "modules" PartMetaFiles = "metadatafiles" PartLyrics = "lyrics" PartRecordings = "recordings" )
The parts, in the order they're offered.
const DirName = "backups"
DirName is the folder in the data folder that holds backups. A reset leaves it alone.
const FormatVersion = 1
FormatVersion is the layout of an archive. An archive with a higher one is refused.
const (
// MinPassword is the shortest password accepted.
MinPassword = 8
)
Variables ¶
var ErrPasswordNeeded = errors.New("this backup is protected: enter its password")
ErrPasswordNeeded: this archive is protected and no password was given.
Functions ¶
func CleanParts ¶
CleanParts checks a list of part IDs against what exists, and returns it in order.
func CountUploads ¶
CountUploads says how many files with this start to their name are waiting in the folder.
func DefaultParts ¶
func DefaultParts() []string
DefaultParts are those on unless someone says otherwise.
func Interrupted ¶
Interrupted names a safety copy from a restore that was cut off part way, or says "". The next start puts it back.
func IsWrongPassword ¶
IsWrongPassword says whether an error is a password that didn't open it.
Types ¶
type AccountInfo ¶
type AccountInfo struct {
Name string `json:"name"`
Admin bool `json:"admin"`
Kind string `json:"kind,omitempty"`
}
AccountInfo says who'd be able to sign in afterwards.
type CryptHeader ¶
type CryptHeader struct {
Alg string `json:"alg"`
KDF string `json:"kdf"`
Time uint32 `json:"time"`
MemoryKiB uint32 `json:"memoryKiB"`
Threads uint8 `json:"threads"`
Salt string `json:"salt"`
Prefix string `json:"noncePrefix"`
Chunk int `json:"chunk"`
}
CryptHeader is how a payload is protected, and isn't secret.
type FileEntry ¶
type FileEntry struct {
Path string `json:"path"`
Part string `json:"part"`
Size int64 `json:"size"`
SHA256 string `json:"sha256"`
}
FileEntry is one file in an archive.
type Info ¶
type Info struct {
Name string `json:"name"`
Size int64 `json:"size"`
Created time.Time `json:"created"`
Auto bool `json:"auto"`
Protected bool `json:"protected"`
Version string `json:"version,omitempty"`
}
Info is a backup kept on this server.
type Inspection ¶
type Inspection struct {
Name string `json:"name"`
Size int64 `json:"size"`
ServerVersion string `json:"serverVersion"`
Created time.Time `json:"created"`
Protected bool `json:"protected"`
Older bool `json:"older"` // made with an older database, which is brought up to date
Parts []PartContent `json:"parts"`
Accounts []AccountInfo `json:"accounts"`
Libraries []LibraryInfo `json:"libraries"`
Addresses []string `json:"addresses"` // places on the network this backup would make the server contact
Dropped []string `json:"dropped"` // what won't be taken from it, and why
HandEdited []string `json:"handEdited"` // metadata files changed since it was made
Problems []string `json:"problems"` // file:line, in those files
Notes []string `json:"notes"`
Needed int64 `json:"needed"` // disk space to unpack it
// contains filtered or unexported fields
}
Inspection is what a check of an archive found: all a person needs to decide, and what's needed to carry on. Nothing has been touched when it's made.
func Inspect ¶
func Inspect(ctx context.Context, archive, password string, f Folders, progress func(Step)) (in *Inspection, err error)
Inspect checks an archive from end to end. It verifies, and touches nothing outside its own work folder. A bad archive returns a *Refusal, a wrong password errWrongPassword.
func (*Inspection) Stage ¶
func (in *Inspection) Stage(ctx context.Context, f Folders, o StageOptions) (*Request, error)
Stage unpacks a checked archive beside the data, and writes the request. Nothing a running server uses is touched: until the next start, this can be taken back.
type Key ¶
type Key struct {
Secret []byte `json:"secret"`
Salt []byte `json:"salt"`
Time uint32 `json:"time"`
MemoryKiB uint32 `json:"memoryKiB"`
Threads uint8 `json:"threads"`
}
Key is what a password turned into, for use later without keeping the password. A schedule keeps one. It opens archives made with it, so it's a secret like any other.
type LibraryInfo ¶
type LibraryInfo struct {
Name string `json:"name"`
Type string `json:"type"`
Folders []string `json:"folders"`
Items int64 `json:"items"`
}
LibraryInfo says which folders on this machine the server would be pointed at.
type Manifest ¶
type Manifest struct {
Format int `json:"format"`
App string `json:"app"`
ServerVersion string `json:"serverVersion"`
Created time.Time `json:"created"`
Schema db.Versions `json:"schema"`
Protected bool `json:"protected"` // made with a password, and holds secrets
Auto bool `json:"auto,omitempty"` // made by the schedule
Parts []PartSummary `json:"parts"` // what was asked for and found
Files []FileEntry `json:"files,omitempty"` // left out of the outer manifest of a protected archive
DataDir string `json:"dataDir,omitempty"`
Crypt *CryptHeader `json:"crypt,omitempty"` // how the payload is protected
}
Manifest describes an archive: what made it, what's in it, and a hash of each file. The hashes catch damage. They can't prove nobody changed the archive on purpose, as anyone can write new ones: only a password can do that.
type Options ¶
type Options struct {
Folders Folders
Parts []string
// LiveDB is the running server's database. Without it, the file is opened to read.
LiveDB *sql.DB
// Password or Key protects the archive. With neither, secrets are left out.
Password string
Key *Key
// SecretSettings are settings that hold keys and passwords, on top of those that
// look like it by their name.
SecretSettings []string
ServerVersion string
Auto bool
// Output is the archive's path. Empty: a new name in the backups folder.
Output string
// Progress is told how far along it is. It may be nil.
Progress func(Step)
// Problem is told about something left out that the backup carries on without.
Problem func(file, why string)
}
Options say what to make.
type Part ¶
type Part struct {
ID string `json:"id"`
Label string `json:"label"`
Desc string `json:"desc"`
Default bool `json:"default"`
Needs []string `json:"needs,omitempty"` // parts it makes no sense without
HasTables bool `json:"hasTables,omitempty"`
}
Part is one of the things a backup can hold.
type PartContent ¶
type PartContent struct {
ID string `json:"id"`
Label string `json:"label"`
Desc string `json:"desc"`
Files int `json:"files"`
Bytes int64 `json:"bytes"`
Rows int64 `json:"rows"`
Needs []string `json:"needs,omitempty"`
HasFiles bool `json:"hasFiles"`
}
PartContent is one part of what's inside.
type PartSummary ¶
type PartSummary struct {
ID string `json:"id"`
Files int `json:"files"`
Bytes int64 `json:"bytes"`
}
PartSummary is what the manifest says about one part.
type Request ¶
type Request struct {
Mode string `json:"mode"` // restore or undo
Parts []string `json:"parts,omitempty"`
HasDB bool `json:"hasDB"`
Copy string `json:"copy,omitempty"` // undo: the safety copy to bring back
Name string `json:"name,omitempty"` // the archive it came from
At time.Time `json:"at"`
}
Request is what the next start is to do.
type Result ¶
type Result struct {
OK bool `json:"ok"`
Mode string `json:"mode"`
Name string `json:"name,omitempty"`
Parts []string `json:"parts,omitempty"`
Safety string `json:"safety,omitempty"` // the safety copy, by name
Error string `json:"error,omitempty"`
Notes []string `json:"notes,omitempty"`
At time.Time `json:"at"`
}
Result says how it went.
type SafetyCopy ¶
SafetyCopy is one kept from an earlier restore.
func SafetyCopies ¶
func SafetyCopies(f Folders) []SafetyCopy
SafetyCopies lists what earlier restores moved aside, newest first.