dar-backup 1.0.0__py3-none-any.whl → 1.0.1__py3-none-any.whl

dar_backup/dar_backup.py

@@ -12,9 +12,6 @@ See section 15 and section 16 in the supplied "LICENSE" file
 
 This script can be used to control `dar` to backup parts of or the whole system.
 """
-
-
-
 import argcomplete
 import argparse
 import filecmp
@@ -25,9 +22,9 @@ import re
 import shlex
 import shutil
 import subprocess
+import configparser
 import xml.etree.ElementTree as ET
 import tempfile
-import threading
 
 from argparse import ArgumentParser
 from datetime import datetime
@@ -39,7 +36,6 @@ from sys import version_info
 from time import time
 from rich.console import Console
 from rich.text import Text
-from threading import Event
 from typing import List, Tuple
 
 from . import __about__ as about
@@ -51,17 +47,18 @@ from dar_backup.util import BackupError
 from dar_backup.util import RestoreError
 from dar_backup.util import requirements
 from dar_backup.util import show_version
+from dar_backup.util import get_config_file
 from dar_backup.util import get_invocation_command_line
 from dar_backup.util import get_binary_info
 from dar_backup.util import print_aligned_settings
 from dar_backup.util import backup_definition_completer, list_archive_completer
 from dar_backup.util import show_scriptname
 from dar_backup.util import print_debug
+from dar_backup.util import send_discord_message
 
 from dar_backup.command_runner import CommandRunner   
 from dar_backup.command_runner import CommandResult
 
-from dar_backup.rich_progress import show_log_driven_bar
 
 from argcomplete.completers import FilesCompleter
 
@@ -99,29 +96,11 @@ def generic_backup(type: str, command: List[str], backup_file: str, backup_defin
 
     logger.info(f"===> Starting {type} backup for {backup_definition}")
     try:
-        log_basename = os.path. dirname(config_settings.logfile_location)
-        logfile = os.path.basename(config_settings.logfile_location)[:-4] + "-commands.log"
-        log_path = os.path.join( log_basename, logfile)
-        logger.debug(f"Commands log file: {log_path}")
-
-        # wrap a progress bar around the dar command
-        stop_event = Event()
-        session_marker = f"=== START BACKUP SESSION: {int(time())} ==="
-        get_logger(command_output_logger=True).info(session_marker)
-        progress_thread = threading.Thread(
-            target=show_log_driven_bar,
-            args=(log_path, stop_event, session_marker),
-            daemon=True
-        )
-        progress_thread.start()
         try:
-            process = runner.run(command, timeout = config_settings.command_timeout_secs)
+            process = runner.run(command, timeout=config_settings.command_timeout_secs)
         except Exception as e:
             print(f"[!] Backup failed: {e}")
             raise
-        finally:
-            stop_event.set()
-            progress_thread.join()
 
         if process.returncode == 0:
             logger.info(f"{type} backup completed successfully.")
@@ -227,6 +206,39 @@ def find_files_between_min_and_max_size(backed_up_files: list[(str, str)], confi
     return files
 
 
+def filter_restoretest_candidates(files: List[str], config_settings: ConfigSettings) -> List[str]:
+    prefixes = [
+        prefix.lstrip("/").lower()
+        for prefix in getattr(config_settings, "restoretest_exclude_prefixes", [])
+    ]
+    suffixes = [
+        suffix.lower()
+        for suffix in getattr(config_settings, "restoretest_exclude_suffixes", [])
+    ]
+    regex = getattr(config_settings, "restoretest_exclude_regex", None)
+
+    if not prefixes and not suffixes and not regex:
+        return files
+
+    filtered = []
+    for path in files:
+        normalized = path.lstrip("/")
+        lowered = normalized.lower()
+        if prefixes and any(lowered.startswith(prefix) for prefix in prefixes):
+            continue
+        if suffixes and any(lowered.endswith(suffix) for suffix in suffixes):
+            continue
+        if regex and regex.search(normalized):
+            continue
+        filtered.append(path)
+
+    if logger:
+        excluded = len(files) - len(filtered)
+        if excluded:
+            logger.debug(f"Restore test filter excluded {excluded} of {len(files)} candidates")
+    return filtered
+
+
 def verify(args: argparse.Namespace, backup_file: str, backup_definition: str, config_settings: ConfigSettings):
     """
     Verify the integrity of a DAR backup by performing the following steps:
@@ -251,29 +263,11 @@ def verify(args: argparse.Namespace, backup_file: str, backup_definition: str, c
     command = ['dar', '-t', backup_file, '-N', '-Q']
  
  
-    log_basename = os.path. dirname(config_settings.logfile_location)
-    logfile = os.path.basename(config_settings.logfile_location)[:-4] + "-commands.log"
-    log_path = os.path.join( log_basename, logfile)
-
-    # wrap a progress bar around the dar command
-    stop_event = Event()
-    session_marker = f"=== START BACKUP SESSION: {int(time())} ==="
-    get_logger(command_output_logger=True).info(session_marker)
-
-    progress_thread = threading.Thread(
-        target=show_log_driven_bar,
-        args=(log_path, stop_event, session_marker),
-        daemon=True
-    )
-    progress_thread.start()
     try:
-        process = runner.run(command, timeout = config_settings.command_timeout_secs)
+        process = runner.run(command, timeout=config_settings.command_timeout_secs)
     except Exception as e:
         print(f"[!] Backup failed: {e}")
         raise
-    finally:
-        stop_event.set()
-        progress_thread.join()
 
 
     if process.returncode == 0:
@@ -287,8 +281,11 @@ def verify(args: argparse.Namespace, backup_file: str, backup_definition: str, c
     backed_up_files = get_backed_up_files(backup_file, config_settings.backup_dir) 
 
     files = find_files_between_min_and_max_size(backed_up_files, config_settings)
+    files = filter_restoretest_candidates(files, config_settings)
     if len(files) == 0:
-        logger.info(f"No files between {config_settings.min_size_verification_mb}MB and {config_settings.max_size_verification_mb}MB for verification, skipping")
+        logger.info(
+            "No files eligible for verification after size and restore-test filters, skipping"
+        )
         return result
 
     # find Root path in backup definition
@@ -312,6 +309,13 @@ def verify(args: argparse.Namespace, backup_file: str, backup_definition: str, c
     if len(files) < config_settings.no_files_verification:
         no_files_verification = len(files)
     random_files = random.sample(files, no_files_verification)
+
+    # Ensure restore directory exists for verification restores
+    try:
+        os.makedirs(config_settings.test_restore_dir, exist_ok=True)
+    except OSError as exc:
+        raise BackupError(f"Cannot create restore directory '{config_settings.test_restore_dir}': {exc}") from exc
+
     for restored_file_path in random_files:
         try:
             args.verbose and logger.info(f"Restoring file: '{restored_file_path}' from backup to: '{config_settings.test_restore_dir}' for file comparing")
@@ -465,6 +469,100 @@ def create_backup_command(backup_type: str, backup_file: str, darrc: str, backup
     return base_command
 
 
+def validate_required_directories(config_settings: ConfigSettings) -> None:
+    """
+    Ensure configured directories exist; raise if any are missing.
+    """
+    required = [
+        ("BACKUP_DIR", config_settings.backup_dir),
+        ("BACKUP.D_DIR", config_settings.backup_d_dir),
+        ("TEST_RESTORE_DIR", config_settings.test_restore_dir),
+    ]
+    manager_db_dir = getattr(config_settings, "manager_db_dir", None)
+    if manager_db_dir:
+        required.append(("MANAGER_DB_DIR", manager_db_dir))
+
+    missing = [(name, path) for name, path in required if not path or not os.path.isdir(path)]
+    if missing:
+        details = "; ".join(f"{name}={path}" for name, path in missing)
+        raise RuntimeError(f"Required directories missing or not accessible: {details}")
+
+
+def preflight_check(args: argparse.Namespace, config_settings: ConfigSettings) -> bool:
+    """
+    Run preflight checks to validate environment before backup.
+    """
+    errors = []
+
+    def check_dir(name: str, path: str, require_write: bool = True):
+        if not path:
+            errors.append(f"{name} is not set")
+            return
+        if not os.path.isdir(path):
+            errors.append(f"{name} does not exist: {path}")
+            return
+        if require_write and not os.access(path, os.W_OK):
+            errors.append(f"{name} is not writable: {path}")
+
+    # Directories and permissions
+    check_dir("BACKUP_DIR", config_settings.backup_dir)
+    check_dir("BACKUP.D_DIR", config_settings.backup_d_dir)
+    check_dir("TEST_RESTORE_DIR", config_settings.test_restore_dir)
+    if getattr(config_settings, "manager_db_dir", None):
+        check_dir("MANAGER_DB_DIR", config_settings.manager_db_dir)
+
+    # Log directory write access
+    log_dir = os.path.dirname(config_settings.logfile_location)
+    check_dir("LOGFILE_LOCATION directory", log_dir)
+
+    # Binaries present
+    for cmd in ("dar",):
+        if shutil.which(cmd) is None:
+            errors.append(f"Binary not found on PATH: {cmd}")
+    if getattr(config_settings, "par2_enabled", False):
+        if shutil.which("par2") is None:
+            errors.append("Binary not found on PATH: par2 (required when PAR2.ENABLED is true)")
+
+    # Binaries respond to --version (basic health)
+    for cmd in ("dar",):
+        if shutil.which(cmd):
+            try:
+                subprocess.run([cmd, "--version"], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=True)
+            except Exception:
+                errors.append(f"Failed to run '{cmd} --version'")
+    if getattr(config_settings, "par2_enabled", False) and shutil.which("par2"):
+        try:
+            subprocess.run(["par2", "--version"], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=True)
+        except Exception:
+            errors.append("Failed to run 'par2 --version'")
+
+    # Restore scratch: can create/clean temp file
+    scratch_test_file = os.path.join(config_settings.test_restore_dir, ".dar-backup-preflight")
+    try:
+        os.makedirs(config_settings.test_restore_dir, exist_ok=True)
+        with open(scratch_test_file, "w") as f:
+            f.write("ok")
+        os.remove(scratch_test_file)
+    except Exception as exc:
+        errors.append(f"Cannot write to TEST_RESTORE_DIR ({config_settings.test_restore_dir}): {exc}")
+
+    # Config sanity: backup definition exists if provided
+    if args.backup_definition:
+        candidate = os.path.join(config_settings.backup_d_dir, args.backup_definition)
+        if not os.path.isfile(candidate):
+            errors.append(f"Backup definition not found: {candidate}")
+
+    if errors:
+        print("Preflight checks failed:")
+        for err in errors:
+            print(f" - {err}")
+        return False
+
+    if os.environ.get("PYTEST_CURRENT_TEST"):
+        print("Preflight checks passed.")
+
+    return True
+
 
 def perform_backup(args: argparse.Namespace, config_settings: ConfigSettings, backup_type: str) -> List[str]:
     """
@@ -500,14 +598,16 @@ def perform_backup(args: argparse.Namespace, config_settings: ConfigSettings, ba
                 backup_definitions.append((file.split('.')[0], os.path.join(root, file)))
 
     for backup_definition, backup_definition_path in backup_definitions:
+        start_len = len(results)
+        success = True
         try:
             date = datetime.now().strftime('%Y-%m-%d')
             backup_file = os.path.join(config_settings.backup_dir, f"{backup_definition}_{backup_type}_{date}")
 
             if os.path.exists(backup_file + '.1.dar'):
                 msg = f"Backup file {backup_file}.1.dar already exists. Skipping backup [1]."
-                logger.error(msg)
-                results.append((msg, 1))
+                logger.warning(msg)
+                results.append((msg, 2))
                 continue
 
             latest_base_backup = None
@@ -551,19 +651,125 @@ def perform_backup(args: argparse.Namespace, config_settings: ConfigSettings, ba
             else:
                 msg = f"Verification of '{backup_file}' failed."
                 logger.error(msg)
-                results.append((msg, 1))
+                results.append((msg, 2))
             logger.info("Generate par2 redundancy files.")
-            generate_par2_files(backup_file, config_settings, args)
+            generate_par2_files(backup_file, config_settings, args, backup_definition=backup_definition)
             logger.info("par2 files completed successfully.")
 
         except Exception as e:
             results.append((repr(e), 1))
             logger.exception(f"Error during {backup_type} backup process, continuing to next backup definition.")
+            success = False
+        finally:
+            # Determine status based on new results for this backup definition
+            new_results = results[start_len:]
+            has_error = any(code == 1 for _, code in new_results)
+            has_warning = any(code == 2 for _, code in new_results)
+            if has_error:
+                success = False
+
+            # Avoid spamming from example/demo backup definitions
+            if backup_definition.lower() == "example":
+                logger.debug("Skipping Discord notification for example backup definition.")
+                continue
+
+            if has_error:
+                status = "FAILURE"
+            elif has_warning:
+                status = "WARNING"
+            else:
+                status = "SUCCESS"
+            timestamp = datetime.now().strftime("%Y-%m-%d_%H:%M")
+            message = f"{timestamp} - dar-backup, {backup_definition}: {status}"
+            if not send_discord_message(message, config_settings=config_settings):
+                logger.debug(f"Discord notification not sent for {backup_definition}: {status}")
 
     logger.trace(f"perform_backup() results[]: {results}")
     return results
 
-def generate_par2_files(backup_file: str, config_settings: ConfigSettings, args):
+def _parse_archive_base(backup_file: str) -> str:
+    return os.path.basename(backup_file)
+
+
+def _list_dar_slices(archive_dir: str, archive_base: str) -> List[str]:
+    pattern = re.compile(rf"{re.escape(archive_base)}\.([0-9]+)\.dar$")
+    dar_slices: List[str] = []
+
+    for filename in os.listdir(archive_dir):
+        match = pattern.match(filename)
+        if match:
+            dar_slices.append(filename)
+
+    dar_slices.sort(key=lambda x: int(pattern.match(x).group(1)))
+    return dar_slices
+
+
+def _validate_slice_sequence(dar_slices: List[str], archive_base: str) -> None:
+    pattern = re.compile(rf"{re.escape(archive_base)}\.([0-9]+)\.dar$")
+    if not dar_slices:
+        raise RuntimeError(f"No dar slices found for archive base: {archive_base}")
+    slice_numbers = [int(pattern.match(s).group(1)) for s in dar_slices]
+    expected = list(range(1, max(slice_numbers) + 1))
+    if slice_numbers != expected:
+        raise RuntimeError(f"Missing dar slices for archive {archive_base}: expected {expected}, got {slice_numbers}")
+
+
+def _get_backup_type_from_archive_base(archive_base: str) -> str:
+    parts = archive_base.split('_')
+    if len(parts) < 3:
+        raise RuntimeError(f"Unexpected archive name format: {archive_base}")
+    return parts[1]
+
+
+def _get_par2_ratio(backup_type: str, par2_config: dict, default_ratio: int) -> int:
+    backup_type = backup_type.upper()
+    if backup_type == "FULL" and par2_config.get("par2_ratio_full") is not None:
+        return par2_config["par2_ratio_full"]
+    if backup_type == "DIFF" and par2_config.get("par2_ratio_diff") is not None:
+        return par2_config["par2_ratio_diff"]
+    if backup_type == "INCR" and par2_config.get("par2_ratio_incr") is not None:
+        return par2_config["par2_ratio_incr"]
+    return default_ratio
+
+
+def _write_par2_manifest(
+    manifest_path: str,
+    archive_dir_relative: str,
+    archive_base: str,
+    archive_files: List[str],
+    dar_backup_version: str,
+    dar_version: str
+) -> None:
+    config = configparser.ConfigParser()
+    config["MANIFEST"] = {
+        "archive_dir_relative": archive_dir_relative,
+        "archive_base": archive_base,
+        "dar_backup_version": dar_backup_version,
+        "dar_version": dar_version,
+        "created_utc": datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%SZ"),
+    }
+    config["ARCHIVE_FILES"] = {
+        "files": "\n".join(archive_files)
+    }
+
+    with open(manifest_path, "w", encoding="utf-8") as f:
+        config.write(f)
+
+
+def _default_par2_config(config_settings: ConfigSettings) -> dict:
+    return {
+        "par2_dir": getattr(config_settings, "par2_dir", None),
+        "par2_layout": getattr(config_settings, "par2_layout", "by-backup"),
+        "par2_mode": getattr(config_settings, "par2_mode", None),
+        "par2_ratio_full": getattr(config_settings, "par2_ratio_full", None),
+        "par2_ratio_diff": getattr(config_settings, "par2_ratio_diff", None),
+        "par2_ratio_incr": getattr(config_settings, "par2_ratio_incr", None),
+        "par2_run_verify": getattr(config_settings, "par2_run_verify", None),
+        "par2_enabled": getattr(config_settings, "par2_enabled", True),
+    }
+
+
+def generate_par2_files(backup_file: str, config_settings: ConfigSettings, args, backup_definition: str = None):
     """
     Generate PAR2 files for a given backup file in the specified backup directory.
 
@@ -571,6 +777,7 @@ def generate_par2_files(backup_file: str, config_settings: ConfigSettings, args)
         backup_file (str): The name of the backup file.
         config_settings: The configuration settings object.
         args: The command-line arguments object.
+        backup_definition (str): The backup definition name used for per-backup overrides.
 
     Raises:
         subprocess.CalledProcessError: If the par2 command fails to execute.
@@ -578,38 +785,58 @@ def generate_par2_files(backup_file: str, config_settings: ConfigSettings, args)
     Returns:
         None
     """
-    # Regular expression to match DAR slice files
-    dar_slice_pattern = re.compile(rf"{re.escape(os.path.basename(backup_file))}\.([0-9]+)\.dar")
-
-    # List of DAR slice files to be processed
-    dar_slices: List[str] = []
-
-    for filename in os.listdir(config_settings.backup_dir):
-        match = dar_slice_pattern.match(filename)
-        if match:
-            dar_slices.append(filename)
-
-    # Sort the DAR slices based on the slice number
-    dar_slices.sort(key=lambda x: int(dar_slice_pattern.match(x).group(1)))
+    if hasattr(config_settings, "get_par2_config"):
+        par2_config = config_settings.get_par2_config(backup_definition)
+    else:
+        par2_config = _default_par2_config(config_settings)
+    if not par2_config.get("par2_enabled", False):
+        logger.debug("PAR2 disabled for this backup definition, skipping.")
+        return
+
+    archive_dir = config_settings.backup_dir
+    archive_base = _parse_archive_base(backup_file)
+    backup_type = _get_backup_type_from_archive_base(archive_base)
+    par2_dir = par2_config.get("par2_dir")
+    if par2_dir:
+        par2_dir = os.path.expanduser(os.path.expandvars(par2_dir))
+        os.makedirs(par2_dir, exist_ok=True)
+
+    ratio = _get_par2_ratio(backup_type, par2_config, config_settings.error_correction_percent)
+
+    dar_slices = _list_dar_slices(archive_dir, archive_base)
+    _validate_slice_sequence(dar_slices, archive_base)
     number_of_slices = len(dar_slices)
-    counter = 1
-
-    for slice_file in dar_slices:
-        file_path = os.path.join(config_settings.backup_dir, slice_file)
-    
-        logger.info(f"{counter}/{number_of_slices}: Now generating par2 files for {file_path}")
-
-        # Run the par2 command to generate redundancy files with error correction
-        command = ['par2', 'create', f'-r{config_settings.error_correction_percent}', '-q', '-q', file_path]
-        process = runner.run(command, timeout = config_settings.command_timeout_secs)
 
-        if process.returncode == 0:
-            logger.info(f"{counter}/{number_of_slices}: Done")
-        else:
-            logger.error(f"Error generating par2 files for {file_path}")
-            raise subprocess.CalledProcessError(process.returncode, command)
-        counter += 1
+    par2_output_dir = par2_dir or archive_dir
+    par2_path = os.path.join(par2_output_dir, f"{archive_base}.par2")
+    dar_slice_paths = [os.path.join(archive_dir, slice_file) for slice_file in dar_slices]
+    logger.info(f"Generating par2 set for archive: {archive_base}")
+    command = ['par2', 'create', '-B', archive_dir, f'-r{ratio}', '-q', '-q', par2_path] + dar_slice_paths
+    process = runner.run(command, timeout=config_settings.command_timeout_secs)
+    if process.returncode != 0:
+        logger.error(f"Error generating par2 files for {archive_base}")
+        raise subprocess.CalledProcessError(process.returncode, command)
+
+    if par2_dir:
+        archive_dir_relative = os.path.relpath(archive_dir, par2_dir)
+        manifest_path = f"{par2_path}.manifest.ini"
+        _write_par2_manifest(
+            manifest_path=manifest_path,
+            archive_dir_relative=archive_dir_relative,
+            archive_base=archive_base,
+            archive_files=dar_slices,
+            dar_backup_version=about.__version__,
+            dar_version=getattr(args, "dar_version", "unknown")
+        )
+        logger.info(f"Wrote par2 manifest: {manifest_path}")
 
+    if par2_config.get("par2_run_verify"):
+        logger.info(f"Verifying par2 set for archive: {archive_base}")
+        verify_command = ['par2', 'verify', '-B', archive_dir, par2_path]
+        verify_process = runner.run(verify_command, timeout=config_settings.command_timeout_secs)
+        if verify_process.returncode != 0:
+            raise subprocess.CalledProcessError(verify_process.returncode, verify_command)
+    return
 
 
 def filter_darrc_file(darrc_path):
@@ -765,6 +992,14 @@ def print_readme(path: str = None, pretty: bool = True):
         path = Path(__file__).parent / "README.md"
     print_markdown(str(path), pretty=pretty)
 
+def list_definitions(backup_d_dir: str) -> List[str]:
+    """
+    Return backup definition filenames from BACKUP.D_DIR, sorted by name.
+    """
+    dir_path = Path(backup_d_dir)
+    if not dir_path.is_dir():
+        raise RuntimeError(f"BACKUP.D_DIR does not exist or is not a directory: {backup_d_dir}")
+    return sorted([entry.name for entry in dir_path.iterdir() if entry.is_file()])
 
 
 def main():
@@ -782,15 +1017,24 @@ def main():
     parser.add_argument('-I', '--incremental-backup', action='store_true', help="Perform incremental backup.")
     parser.add_argument('-d', '--backup-definition', help="Specific 'recipe' to select directories and files.").completer = backup_definition_completer
     parser.add_argument('--alternate-reference-archive', help="DIFF or INCR compared to specified archive.").completer = list_archive_completer
-    parser.add_argument('-c', '--config-file', type=str, help="Path to 'dar-backup.conf'", default='~/.config/dar-backup/dar-backup.conf')
+    parser.add_argument('-c', '--config-file', type=str, help="Path to 'dar-backup.conf'", default=None)
     parser.add_argument('--darrc', type=str, help='Optional path to .darrc')
-    parser.add_argument('-l', '--list', action='store_true', help="List available archives.").completer = list_archive_completer
+    parser.add_argument(
+        '-l',
+        '--list',
+        nargs='?',
+        const=True,
+        default=False,
+        help="List available archives.",
+    ).completer = list_archive_completer
     parser.add_argument('--list-contents', help="List the contents of the specified archive.").completer = list_archive_completer
+    parser.add_argument('--list-definitions', action='store_true', help="List available backup definitions from BACKUP.D_DIR.")
     parser.add_argument('--selection', type=str, help="Selection string to pass to 'dar', e.g. --selection=\"-I '*.NEF'\"")
 #    parser.add_argument('-r', '--restore', nargs=1, type=str, help="Restore specified archive.")
     parser.add_argument('-r', '--restore', type=str, help="Restore specified archive.").completer = list_archive_completer
     parser.add_argument('--restore-dir',   type=str, help="Directory to restore files to.")
     parser.add_argument('--verbose', action='store_true', help="Print various status messages to screen")
+    parser.add_argument('--preflight-check', action='store_true', help="Run preflight checks and exit")
     parser.add_argument('--suppress-dar-msg', action='store_true', help="cancel dar options in .darrc: -vt, -vs, -vd, -vf and -va")
     parser.add_argument('--log-level', type=str, help="`debug` or `trace`", default="info")
     parser.add_argument('--log-stdout', action='store_true', help='also print log messages to stdout')
@@ -804,6 +1048,11 @@ def main():
     
     argcomplete.autocomplete(parser)
     args = parser.parse_args()
+    # Ensure new flags are present when parse_args is mocked in tests
+    if not hasattr(args, "preflight_check"):
+        args.preflight_check = False
+    if not hasattr(args, "list_definitions"):
+        args.list_definitions = False
 
     if args.version:
         show_version()
@@ -825,19 +1074,56 @@ def main():
         exit(0)
 
 
+    # be backwards compatible with older versions
+    DEFAULT_CONFIG_FILE = "~/.config/dar-backup/dar-backup.conf"
+
+    env_cf = os.getenv("DAR_BACKUP_CONFIG_FILE")
+    env_cf = env_cf.strip() if env_cf else None
 
-    if not args.config_file:
-        print(f"Config file not specified, exiting", file=stderr)
-        exit(1) 
+    cli_cf = args.config_file.strip() if args.config_file else None
     
-    config_settings_path = os.path.expanduser(os.path.expandvars(args.config_file))
-    if not os.path.exists(config_settings_path):
-        print(f"Config file {args.config_file} does not exist.", file=stderr)
-        exit(127)
+    raw_config = (
+        cli_cf
+        or env_cf
+        or DEFAULT_CONFIG_FILE
+    )
+
+    config_settings_path = get_config_file(args)
+
+    if not (os.path.isfile(config_settings_path) and os.access(config_settings_path, os.R_OK)):
+        print(f"Config file {config_settings_path} must exist and be readable.", file=stderr)
+        raise SystemExit(127)
 
     args.config_file = config_settings_path
     config_settings = ConfigSettings(args.config_file)
 
+    if args.list_definitions:
+        try:
+            for name in list_definitions(config_settings.backup_d_dir):
+                print(name)
+        except RuntimeError as exc:
+            print(str(exc), file=stderr)
+            exit(127)
+        exit(0)
+
+    try:
+        validate_required_directories(config_settings)
+    except RuntimeError as exc:
+        ts = datetime.now().strftime("%Y-%m-%d_%H:%M")
+        send_discord_message(f"{ts} - dar-backup: FAILURE - {exc}", config_settings=config_settings)
+        print(str(exc), file=stderr)
+        exit(127)
+
+    # Run preflight checks always; if --preflight-check is set, exit afterward.
+    ok = preflight_check(args, config_settings)
+    if not ok:
+        ts = datetime.now().strftime("%Y-%m-%d_%H:%M")
+        send_discord_message(f"{ts} - dar-backup: FAILURE - preflight checks failed", config_settings=config_settings)
+        exit_code = 127 if args.backup_definition else 1
+        exit(exit_code)
+    if args.preflight_check:
+        exit(0)
+
     command_output_log = config_settings.logfile_location.replace("dar-backup.log", "dar-backup-commands.log")
     if command_output_log == config_settings.logfile_location:
         print(f"Error: logfile_location in {args.config_file} does not end at 'dar-backup.log', exiting", file=stderr)
@@ -873,6 +1159,7 @@ def main():
         logger.debug(f"`Args`:\n{args}")
         logger.debug(f"`Config_settings`:\n{config_settings}")
         dar_properties = get_binary_info(command='dar')
+        args.dar_version = dar_properties.get('version', 'unknown')
         start_msgs.append(('dar path:', dar_properties['path']))
         start_msgs.append(('dar version:', dar_properties['version']))
 
@@ -915,7 +1202,14 @@ def main():
         requirements('PREREQ', config_settings)
 
         if args.list:
-            list_backups(config_settings.backup_dir, args.backup_definition)
+            list_filter = args.backup_definition
+            if isinstance(args.list, str):
+                if list_filter:
+                    if args.list.startswith(list_filter):
+                        list_filter = args.list
+                else:
+                    list_filter = args.list
+            list_backups(config_settings.backup_dir, list_filter)
         elif args.full_backup and not args.differential_backup and not args.incremental_backup:
             results.extend(perform_backup(args, config_settings, "FULL"))
         elif args.differential_backup and not args.full_backup and not args.incremental_backup:
@@ -951,6 +1245,7 @@ def main():
 
     # Determine exit code 
     error = False
+    final_exit_code = 0
     logger.debug(f"results[]: {results}")
     if results:
         i = 0
@@ -961,15 +1256,21 @@ def main():
                 if exit_code > 0:
                     error = True
                     args.verbose and print(msg)
+                    if exit_code == 1:
+                        final_exit_code = 1
+                    elif exit_code == 2 and final_exit_code == 0:
+                        final_exit_code = 2
             else:
                 logger.error(f"not correct result type: {result}, which must be a tuple (<msg>, <exit_code>)")
+                error = True
+                final_exit_code = 1
             i=i+1
             
     console = Console()
     if error:
         if args.verbose:
             console.print(Text("Errors encountered", style="bold red"))
-        exit(1)
+        exit(final_exit_code or 1)
     else:
         if args.verbose:
             console.print(Text("Success: all backups completed", style="bold green"))