diff --git a/docs/configuration/prune.rst b/docs/configuration/prune.rst index 98104b6..3d5d6e8 100644 --- a/docs/configuration/prune.rst +++ b/docs/configuration/prune.rst @@ -51,17 +51,6 @@ Example Configuration: You might have **existing snapshots** of filesystems affected by pruning which you want to keep, i.e. not be destroyed by zrepl. Make sure to actually add the necessary ``regex`` keep rules on both sides, like with ``manual`` in the example above. -.. _prune-attention-issue-102: - -.. ATTENTION:: - - It is currently not possible to define pruning on a source job. - The source job creates snapshots, which means that extended replication downtime will fill up the source's zpool with snapshots, since pruning is directed by the corresponding active side (pull job). - If this is a potential risk for you, consider using :ref:`push mode `. - As a :ref:`temporary workaround` for :issue:`102` you can define a pruning-only :ref:`snap job ` to thin out extremely old snapshots in case the active side doesn't prune for a very long time. - **Note**: Since jobs run in parallel, it is possible for a ``snap`` job to prune snapshots that are queued to be replicated or destroyed by the remote ``pull`` job. - - .. _prune-keep-not-replicated: Policy ``not_replicated`` @@ -169,26 +158,56 @@ Policy ``regex`` Like all other regular expression fields in prune policies, zrepl uses Go's `regexp.Regexp `_ Perl-compatible regular expressions (`Syntax `_). The optional `negate` boolean field inverts the semantics: Use it if you want to keep all snapshots that *do not* match the given regex. -.. _prune-workaround-issue-102: -Workaround for Source-side snapshot pruning -------------------------------------------- +Source-side snapshot pruning +---------------------------- -Using the ``snap`` job type as a workaround for :issue:`102` as mentioned :ref:`here `: +A :ref:`source jobs` takes snapshots on the system it runs on. +The corresponding :ref:`pull job ` on the replication target connects to the source job and replicates the snapshots. +Afterwards, the pull job coordinates pruning on both sender (the source job side) and receiver (the pull job side). + +There is no built-in way to define and execute pruning on the source side independently of the pull side. +The source job will continue taking snapshots which will not be pruned until the pull side connects. +This means that **extended replication downtime will fill up the source's zpool with snapshots**. + +If the above is a conceivable situation for you, consider using :ref:`push mode `, where pruning happens on the same side where snapshots are taken. + +Workaround using ``snap`` job +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As a workaround (see GitHub :issue:`102` for development progress), a pruning-only :ref:`snap job ` can be defined on the source side: +The snap job is in charge of snapshot creation & destruction, whereas the source job's role is reduced to just serving snapshots. +However, since, jobs are run independently, it is possible that the snap job will prune snapshots that are queued for replication / destruction by the remote pull job that connects to the source job. +There is no possible configuration to avoid this problem with the current version of zrepl. + +Example configuration: :: - jobs: - - type: snap - pruning: - keep: - - type: grid - ... + # source side + jobs: + - type: snap + snapshotting: + type: periodic + pruning: + keep: + # source side pruning rules go here + ... - - type: pull - pruning: - keep_sender: - - type: not_replicated - ... - keep_receiver: - ... + - type: source + snapshotting: + type: manual + root_fs: ... + + # pull side + jobs: + - type: pull + pruning: + keep_sender: + # let the source-side snap job do the pruning + - type: regex + regex: ".*" + ... + keep_receiver: + # feel free to prune on the pull side as desired + ...