From 9adfb7560fcd1186153bd743f885c12753abc9e5 Mon Sep 17 00:00:00 2001 From: FĂ©lix Sipma Date: Fri, 29 Apr 2016 11:33:23 +0200 Subject: Attic: add comments --- src/Propellor/Property/Attic.hs | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) (limited to 'src/Propellor/Property/Attic.hs') diff --git a/src/Propellor/Property/Attic.hs b/src/Propellor/Property/Attic.hs index ef74afbd..26f23500 100644 --- a/src/Propellor/Property/Attic.hs +++ b/src/Propellor/Property/Attic.hs @@ -25,6 +25,7 @@ installed = Apt.installed ["attic"] repoExists :: AtticRepo -> IO Bool repoExists repo = boolSystem "attic" [Param "list", File repo] +-- | Inits a new attic repository init :: AtticRepo -> Property DebianLike init backupdir = check (not <$> repoExists backupdir) (cmdProperty "attic" initargs) `requires` installed @@ -34,6 +35,13 @@ init backupdir = check (not <$> repoExists backupdir) (cmdProperty "attic" inita , backupdir ] +-- | Restores a directory from an attic backup. +-- +-- Only does anything if the directory does not exist, or exists, +-- but is completely empty. +-- +-- The restore is performed atomically; restoring to a temp directory +-- and then moving it to the directory. restored :: FilePath -> AtticRepo -> Property DebianLike restored dir backupdir = go `requires` installed where @@ -62,10 +70,31 @@ restored dir backupdir = go `requires` installed , return FailedChange ) +-- | Installs a cron job that causes a given directory to be backed +-- up, by running attic with some parameters. +-- +-- If the directory does not exist, or exists but is completely empty, +-- this Property will immediately restore it from an existing backup. +-- +-- So, this property can be used to deploy a directory of content +-- to a host, while also ensuring any changes made to it get backed up. +-- For example: +-- +-- > & Attic.backup "/srv/git" "root@myserver:/mnt/backup/git.attic" Cron.Daily +-- > ["--exclude=/srv/git/tobeignored"] +-- > [Attic.KeepDays 7, Attic.KeepWeeks 4, Attic.KeepMonths 6, Attic.KeepYears 1] +-- +-- Note that this property does not make attic encrypt the backup +-- repository. +-- +-- Since attic uses a fair amount of system resources, only one attic +-- backup job will be run at a time. Other jobs will wait their turns to +-- run. backup :: FilePath -> AtticRepo -> Cron.Times -> [AtticParam] -> [KeepPolicy] -> Property DebianLike backup dir backupdir crontimes extraargs kp = backup' dir backupdir crontimes extraargs kp `requires` restored dir backupdir +-- | Does a backup, but does not automatically restore. backup' :: FilePath -> AtticRepo -> Cron.Times -> [AtticParam] -> [KeepPolicy] -> Property DebianLike backup' dir backupdir crontimes extraargs kp = cronjob `describe` desc @@ -95,6 +124,10 @@ backup' dir backupdir crontimes extraargs kp = cronjob ++ map keepParam kp +-- | Constructs an AtticParam that specifies which old backup generations to +-- keep. By default, all generations are kept. However, when this parameter is +-- passed to the `backup` property, they will run attic prune to clean out +-- generations not specified here. keepParam :: KeepPolicy -> AtticParam keepParam (KeepHours n) = "--keep-hourly=" ++ show n keepParam (KeepDays n) = "--keep-daily=" ++ show n @@ -102,6 +135,10 @@ keepParam (KeepWeeks n) = "--keep-daily=" ++ show n keepParam (KeepMonths n) = "--keep-monthly=" ++ show n keepParam (KeepYears n) = "--keep-yearly=" ++ show n +-- | Policy for backup generations to keep. For example, KeepDays 30 will +-- keep the latest backup for each day when a backup was made, and keep the +-- last 30 such backups. When multiple KeepPolicies are combined together, +-- backups meeting any policy are kept. See attic's man page for details. data KeepPolicy = KeepHours Int | KeepDays Int -- cgit v1.2.3