Config schema

This module contains the config structure and it's default values.

The config is using the YAML syntax and this file describes the structure of it.

BackupTarget dataclass

BackupTarget(
    source=II(f"..{DEFAULT}.source"),
    destination=II(f"..{DEFAULT}.destination"),
    if_dst_dir_not_found=II(
        f"..{DEFAULT}.if_dst_dir_not_found"
    ),
    restore_strategy=II(f"..{DEFAULT}.restore_strategy"),
    src_snapshot_dir=II(f"..{DEFAULT}.src_snapshot_dir"),
    src_retention=dict(),
    dst_retention=dict(),
    replaced_target_ttl=II(
        f"..{DEFAULT}.replaced_target_ttl"
    ),
    subvolume_rules=II(f"..{DEFAULT}.subvolume_rules"),
)

Defines a single backup target.

Parameters:

Name	Type	Description	Default
source	str | None	Path or URL you want to backup. Needs to be a btrfs subvolume	II(f'..{DEFAULT}.source')
destination	str | None	Path or URL where you want to send snapshots. If None, snapshots will only be on source side	II(f'..{DEFAULT}.destination')
restore_strategy	TargetRestoreStrategy	Default procedure to restore a backup	II(f'..{DEFAULT}.restore_strategy')
src_snapshot_dir	Path	Directory where source snapshots relative to the mount point of the btrfs volume are located	II(f'..{DEFAULT}.src_snapshot_dir')
src_retention	dict[str, dict[str, str]]	Retention rules for snapshots located at the source	dict()
dst_retention	dict[str, dict[str, str]]	Retention rules for snapshots located at the destination	dict()
replaced_target_ttl	str	The minimum time the old replaced subvolume should be kept	II(f'..{DEFAULT}.replaced_target_ttl')
subvolume_rules	dict[str, TargetSubvolume]	Contains rules for how to handle the subvolumes of a target	II(f'..{DEFAULT}.subvolume_rules')

BaseConfig dataclass

BaseConfig(
    backup_targets=lambda: {
        DEFAULT: BackupTarget(
            source=None,
            destination=None,
            if_dst_dir_not_found=OnDestinationDirNotFound.CREATE,
            restore_strategy=TargetRestoreStrategy.SAFE,
            src_snapshot_dir=Path(".b4_backup"),
            src_retention={DEFAULT: {"all": "1"}},
            dst_retention={DEFAULT: {"all": "forever"}},
            replaced_target_ttl="24hours",
            subvolume_rules={
                DEFAULT: TargetSubvolume(
                    backup_strategy=SubvolumeBackupStrategy.FULL,
                    fallback_strategy=SubvolumeFallbackStrategy.DROP,
                ),
                "/": TargetSubvolume(),
            },
        )
    }(),
    default_targets=list(),
    timezone="utc",
    logging=II(
        "oc.create:${from_file:"
        + str(
            Path(__file__).parent
            / "default_logging_config.yml"
        )
        + "}"
    ),
    config_path=Path("~/.config/b4_backup.yml"),
)

The root level of the configuration.

Parameters:

Name	Type	Description	Default
backup_targets	dict[str, BackupTarget]	An object containing all targets to backup	lambda: {DEFAULT: BackupTarget(source=None, destination=None, if_dst_dir_not_found=CREATE, restore_strategy=SAFE, src_snapshot_dir=Path('.b4_backup'), src_retention={DEFAULT: {'all': '1'}}, dst_retention={DEFAULT: {'all': 'forever'}}, replaced_target_ttl='24hours', subvolume_rules={DEFAULT: TargetSubvolume(backup_strategy=FULL, fallback_strategy=DROP), '/': TargetSubvolume()})}()
default_targets	list[str]	List of default targets to use if not specified	list()
timezone	str	Timezone to use	'utc'
logging	dict[str, Any]	Python logging configuration settings (logging.config.dictConfig).	II('oc.create:${from_file:' + str(parent / 'default_logging_config.yml') + '}')

__post_init__

__post_init__()

Used for validation of the values.

Source code in b4_backup/config_schema.py

def __post_init__(self):
    """Used for validation of the values."""
    options = set(self.backup_targets) - {DEFAULT}
    for target in self.default_targets:
        if not any(PurePath(x).is_relative_to(target) for x in options):
            raise omegaconf.errors.ValidationError(
                textwrap.dedent(
                    f"""\
                    Item '{target}' is not in 'backup_targets' but defined in 'default_targets'
                        full_key: default_targets
                        object_type={self.__class__.__name__}"""
                )
            )

OnDestinationDirNotFound

Bases: str, Enum

How to behave, if the destination directory does not exist.

Attributes:

Name	Type	Description
CREATE		Create the missing directory structure and proceed without an error.
FAIL		Throw an error and stop execution.

SubvolumeBackupStrategy

Bases: str, Enum

Backup strategy for subvolumes.

Attributes:

Name	Type	Description
IGNORE		The subvolume will be ignored during the backup
SOURCE_ONLY		The subvolume will be kept only on source and not sent to destination
FULL		The subvolume will be sent to destination

SubvolumeFallbackStrategy

Bases: str, Enum

Fallback strategy for subvolumes on a restore if the backup subvolume is already deleted.

Attributes:

Name	Type	Description
DROP		The subvolume is lost after a restore (Use case: Docker artifacts or everywhere else where btrfs subvolumes are created dynamically)
NEW		An empty subvolume is created at that place (Use case: Cache directories)
KEEP		The old subvolume will be copied at the new place, if doesn't exist, a new one will be created (Use case: Steam library)

TargetRestoreStrategy

Bases: str, Enum

Specifies the restore procedure to be used.

Attributes:

Name	Type	Description
SAFE		Just copy the snapshot back to the source snapshot directory without touching the target directory
REPLACE		Bases safe, but also replace the target subvolumes with the copied one. Works by moving the original target away and then copy the snapshot to that place. Revertable by using the REPLACE snapshot name.

TargetSubvolume dataclass

TargetSubvolume(
    backup_strategy=II(f"..{DEFAULT}.backup_strategy"),
    fallback_strategy=II(f"..{DEFAULT}.fallback_strategy"),
)

Defines how to handle a specific subvolume in a target.

Parameters:

Name	Type	Description	Default
backup_strategy	SubvolumeBackupStrategy	How to handle the subvolume during backup	II(f'..{DEFAULT}.backup_strategy')
fallback_strategy	SubvolumeFallbackStrategy	How to handle the subvolume during restore if the backup subvolume is already deleted	II(f'..{DEFAULT}.fallback_strategy')