|author||Félix Sipma||2016-04-29 11:33:23 +0200|
|committer||Félix Sipma||2016-04-29 11:33:23 +0200|
Attic: add comments
Diffstat (limited to 'src/Propellor/Property/Attic.hs')
1 files changed, 37 insertions, 0 deletions
diff --git a/src/Propellor/Property/Attic.hs b/src/Propellor/Property/Attic.hs
index ef74afbd..26f23500 100644
@@ -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)
@@ -34,6 +35,13 @@ init backupdir = check (not <$> repoExists backupdir) (cmdProperty "attic" inita
+-- | 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
@@ -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
+-- 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
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
@@ -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.
= KeepHours Int
| KeepDays Int