dar-backup 1.0.2__py3-none-any.whl → 1.1.0__py3-none-any.whl

dar_backup/manager.py

@@ -29,6 +29,8 @@ import sys
 import subprocess
 import threading
 import shlex
+import time as time_module
+import dateparser
 
 from inputimeout import inputimeout, TimeoutOccurred
 
@@ -36,6 +38,7 @@ from inputimeout import inputimeout, TimeoutOccurred
 from . import __about__ as about
 from dar_backup.config_settings import ConfigSettings
 from dar_backup.util import setup_logging
+from dar_backup.util import derive_trace_log_path
 from dar_backup.util import CommandResult
 from dar_backup.util import get_config_file
 from dar_backup.util import send_discord_message
@@ -48,12 +51,12 @@ from dar_backup.util import show_scriptname
 
 from dar_backup.command_runner import CommandRunner   
 from dar_backup.command_runner import CommandResult
-from dar_backup.util import backup_definition_completer, list_archive_completer, archive_content_completer, add_specific_archive_completer
+from dar_backup.util import backup_definition_completer, archive_content_completer, add_specific_archive_completer
 
-from datetime import datetime
+from datetime import datetime, tzinfo
 from sys import stderr
 from time import time
-from typing import Dict, List, NamedTuple, Tuple
+from typing import Dict, List, Tuple, Optional
 
 # Constants
 SCRIPTNAME = os.path.basename(__file__)
@@ -464,6 +467,693 @@ def find_file(file, backup_def, config_settings):
     return process.returncode
 
 
+def restore_at(backup_def: str, paths: List[str], when: str, target: str, config_settings: ConfigSettings, verbose: bool = False) -> int:
+    """
+    Perform a Point-in-Time Recovery (PITR) using dar_manager.
+
+    Args:
+        backup_def: Backup definition name (prefix for the catalog DB, e.g. "example").
+        paths: One or more file or directory paths as stored in the DAR catalog
+            (must be relative, e.g. "tmp/unit-test/.../file.txt").
+        when: Date/time string to restore "as of". Parsed via dateparser and
+            converted to dar_manager format YYYY/MM/DD-HH:MM:SS. If None/empty,
+            the latest version is restored.
+        target: Destination directory for restore output. Required to avoid
+            restoring into an unintended working directory. Restore is rebased
+            under this directory using dar options (-R).
+        config_settings: Loaded ConfigSettings used to locate backup dirs/DB and
+            timeouts.
+        verbose: If True, enables dar_manager verbose logging (-v).
+
+    Returns:
+        Process return code (0 on success, non-zero on failure). If dar_manager
+        reports no files restored for a dated PITR, a fallback path is attempted
+        that selects the correct archive via dar_manager metadata and restores
+        the file(s) directly with dar.
+    """
+    database = f"{backup_def}{DB_SUFFIX}"
+    database_path = os.path.join(get_db_dir(config_settings), database)
+    logger.debug(
+        "PITR restore requested: backup_def=%s paths=%d when=%s target=%s db=%s",
+        backup_def,
+        len(paths),
+        when,
+        target,
+        database_path,
+    )
+
+    if not os.path.exists(database_path):
+        logger.error(f'Database not found: "{database_path}"')
+        return 1
+
+    if not target:
+        logger.error("Restore target directory is required (--target).")
+        return 1
+    unsafe_reason = _restore_target_unsafe_reason(target)
+    if unsafe_reason:
+        logger.error(unsafe_reason)
+        return 1
+
+    # Parse date (or default to "now" for latest restore)
+    parsed_date = None
+    if when:
+        parsed_date = _parse_when(when)
+        if parsed_date:
+            date_arg = parsed_date.strftime("%Y/%m/%d-%H:%M:%S")
+            logger.info("Restoring files as of: %s (from input '%s')", date_arg, when)
+            logger.debug("Parsed PITR timestamp: %s -> %s", when, date_arg)
+        else:
+            logger.error(f"Could not parse date: '{when}'")
+            return 1
+    else:
+        parsed_date = datetime.now()
+        logger.info(
+            "Restoring files as of: %s (no --when provided; using current time)",
+            parsed_date.strftime("%Y/%m/%d-%H:%M:%S"),
+        )
+
+    # Target directory handling: pass -R and -n via dar_manager's -e option so dar
+    # rebases paths and fails fast instead of prompting to overwrite.
+    if target:
+        logger.debug("PITR target directory: %s (cwd=%s)", target, os.getcwd())
+        if not os.path.exists(target):
+            try:
+                os.makedirs(target, exist_ok=True)
+            except Exception as e:
+                logger.error(f"Could not create target directory '{target}': {e}")
+                return 1
+            logger.debug("Created target directory: %s", target)
+        # Fail fast if any requested paths already exist under target.
+        normalized_paths = [os.path.normpath(path.lstrip(os.sep)) for path in paths]
+        if normalized_paths:
+            logger.debug("Normalized restore paths count=%d sample=%s", len(normalized_paths), normalized_paths[:3])
+        existing = []
+        for rel_path in normalized_paths:
+            if not rel_path or rel_path == ".":
+                continue
+            candidate = os.path.join(target, rel_path)
+            if os.path.exists(candidate):
+                existing.append(rel_path)
+        if existing:
+            sample = ", ".join(existing[:3])
+            extra = f" (+{len(existing) - 3} more)" if len(existing) > 3 else ""
+            logger.error(
+                "Restore target '%s' already contains path(s) to restore: %s%s. For safety, PITR restores abort "
+                "without overwriting existing files. Use a clean/empty target.",
+                target,
+                sample,
+                extra,
+            )
+            return 1
+
+    # For PITR restores, skip dar_manager -w restore to avoid interactive prompts.
+    # Use dar_manager metadata for selection, then restore directly with dar.
+    logger.info(
+        "PITR restore uses direct dar restore with catalog-derived chain (non-interactive)."
+    )
+    return _restore_with_dar(backup_def, paths, parsed_date, target, config_settings)
+
+
+def _restore_target_unsafe_reason(target: str) -> Optional[str]:
+    target_abs = os.path.abspath(target)
+    target_norm = os.path.normpath(target_abs)
+
+    allow_prefixes = (
+        "/tmp",
+        "/var/tmp",
+        "/home",
+    )
+    if target_norm in allow_prefixes or target_norm.startswith(allow_prefixes):
+        return None
+
+    protected_prefixes = (
+        "/bin",
+        "/sbin",
+        "/usr",
+        "/etc",
+        "/lib",
+        "/lib64",
+        "/boot",
+        "/proc",
+        "/sys",
+        "/dev",
+        "/var",
+        "/root",
+    )
+    if target_norm == "/" or target_norm in protected_prefixes:
+        return f"Restore target '{target_norm}' is a protected system directory. Choose a safer location."
+    if any(target_norm.startswith(prefix + os.sep) for prefix in protected_prefixes):
+        return f"Restore target '{target_norm}' is under a protected system directory. Choose a safer location."
+
+    return None
+
+
+def _local_tzinfo() -> tzinfo:
+    return datetime.now().astimezone().tzinfo
+
+
+def _normalize_when_dt(dt: datetime) -> datetime:
+    if dt.tzinfo is None or dt.tzinfo.utcoffset(dt) is None:
+        return dt
+    local_tz = _local_tzinfo()
+    return dt.astimezone(local_tz).replace(tzinfo=None)
+
+
+def _parse_when(when: str) -> Optional[datetime]:
+    parsed = dateparser.parse(when)
+    if not parsed:
+        return None
+    normalized = _normalize_when_dt(parsed)
+    if normalized is not parsed:
+        logger.debug("Normalized PITR timestamp with timezone: %s -> %s", parsed, normalized)
+    return normalized
+
+
+def _coerce_timeout(value: Optional[int]) -> Optional[int]:
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return None if value <= 0 else value
+    if isinstance(value, str):
+        try:
+            value_int = int(value)
+        except ValueError:
+            return None
+        return None if value_int <= 0 else value_int
+    return None
+
+
+def _parse_archive_map(list_output: str) -> Dict[int, str]:
+    archives: Dict[int, str] = {}
+    for line in list_output.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("archive #") or stripped.startswith("-"):
+            continue
+        parts = stripped.split()
+        if len(parts) < 3 or not parts[0].isdigit():
+            continue
+        num = int(parts[0])
+        basename = parts[-1]
+        path = " ".join(parts[1:-1])
+        archives[num] = os.path.join(path, basename)
+    return archives
+
+
+def _replace_path_prefix(path: str, old_prefix: str, new_prefix: str) -> Optional[str]:
+    old_norm = os.path.normpath(old_prefix)
+    new_norm = os.path.normpath(new_prefix)
+    if path == old_norm:
+        return new_norm
+    if path.startswith(old_norm + os.sep):
+        suffix = path[len(old_norm):]
+        return os.path.normpath(new_norm + suffix)
+    return None
+
+
+def relocate_archive_paths(
+    backup_def: str,
+    old_prefix: str,
+    new_prefix: str,
+    config_settings: ConfigSettings,
+    dry_run: bool = False,
+) -> int:
+    database = f"{backup_def}{DB_SUFFIX}"
+    database_path = os.path.join(get_db_dir(config_settings), database)
+    if not os.path.exists(database_path):
+        logger.error(f'Database not found: "{database_path}"')
+        return 1
+
+    timeout = _coerce_timeout(getattr(config_settings, "command_timeout_secs", None))
+    list_result = runner.run(["dar_manager", "--base", database_path, "--list"], timeout=timeout)
+    stdout = list_result.stdout or ""
+    stderr = list_result.stderr or ""
+    if list_result.returncode != 0:
+        logger.error(f'Error listing catalogs for: "{database_path}"')
+        logger.error(f"stderr: {stderr}")
+        logger.error(f"stdout: {stdout}")
+        return list_result.returncode
+
+    archive_map = _parse_archive_map(stdout)
+    if not archive_map:
+        logger.error("Could not determine archive list from dar_manager output.")
+        return 1
+
+    updates: List[Tuple[int, str, str, str]] = []
+    for catalog_no, full_path in archive_map.items():
+        current_dir = os.path.dirname(full_path)
+        new_dir = _replace_path_prefix(current_dir, old_prefix, new_prefix)
+        if new_dir and new_dir != current_dir:
+            updates.append((catalog_no, current_dir, new_dir, os.path.basename(full_path)))
+
+    if not updates:
+        logger.info(
+            "No archive paths matched '%s' in database '%s'.",
+            os.path.normpath(old_prefix),
+            database_path,
+        )
+        return 0
+
+    logger.info(
+        "Updating %d archive path(s) from '%s' to '%s' in database '%s'.",
+        len(updates),
+        os.path.normpath(old_prefix),
+        os.path.normpath(new_prefix),
+        database_path,
+    )
+    failures = 0
+    for catalog_no, current_dir, new_dir, basename in updates:
+        logger.info("Archive #%d (%s): %s -> %s", catalog_no, basename, current_dir, new_dir)
+        if dry_run:
+            continue
+        result = runner.run(
+            ["dar_manager", "--base", database_path, "-p", str(catalog_no), new_dir],
+            timeout=timeout,
+        )
+        if result.returncode != 0:
+            failures += 1
+            logger.error(
+                "Failed updating archive #%d path to '%s' (returncode=%s).",
+                catalog_no,
+                new_dir,
+                result.returncode,
+            )
+            logger.error(f"stderr: {result.stderr}")
+
+    if failures:
+        logger.error("Relocate completed with %d failure(s).", failures)
+        return 1
+    logger.info("Relocate completed successfully.")
+    return 0
+
+
+def _parse_archive_info(archive_map: Dict[int, str]) -> List[Tuple[int, datetime, str]]:
+    info: List[Tuple[int, datetime, str]] = []
+    pattern = re.compile(r"^(.*)_(FULL|DIFF|INCR)_(\d{4}-\d{2}-\d{2})(?:_(\d{6}))?(?:_.*)?$")
+    for catalog_no, path in archive_map.items():
+        base = os.path.basename(path)
+        match = pattern.match(base)
+        if not match:
+            continue
+        _, archive_type, date_str, time_str = match.groups()
+        try:
+            if time_str:
+                archive_date = datetime.strptime(f"{date_str}_{time_str}", "%Y-%m-%d_%H%M%S")
+            else:
+                archive_date = datetime.strptime(date_str, "%Y-%m-%d")
+        except ValueError:
+            continue
+        info.append((catalog_no, archive_date, archive_type))
+    return info
+
+
+def _select_archive_chain(archive_info: List[Tuple[int, datetime, str]], when_dt: datetime) -> List[int]:
+    order = {"FULL": 0, "DIFF": 1, "INCR": 2}
+    candidates = [
+        (catalog_no, date, archive_type)
+        for catalog_no, date, archive_type in archive_info
+        if date <= when_dt
+    ]
+    candidates.sort(key=lambda item: (item[1], order.get(item[2], 99), item[0]))
+    last_full = None
+    last_full_key = None
+    for catalog_no, date, archive_type in candidates:
+        if archive_type == "FULL":
+            last_full = catalog_no
+            last_full_key = (date, order["FULL"], catalog_no)
+    if last_full is None:
+        return []
+
+    last_diff = None
+    last_diff_key = None
+    for catalog_no, date, archive_type in candidates:
+        key = (date, order.get(archive_type, 99), catalog_no)
+        if key <= last_full_key:
+            continue
+        if archive_type == "DIFF":
+            last_diff = catalog_no
+            last_diff_key = key
+
+    base_key = last_diff_key or last_full_key
+    last_incr = None
+    for catalog_no, date, archive_type in candidates:
+        key = (date, order.get(archive_type, 99), catalog_no)
+        if key <= base_key:
+            continue
+        if archive_type == "INCR":
+            last_incr = catalog_no
+
+    chain = [last_full]
+    if last_diff is not None:
+        chain.append(last_diff)
+    if last_incr is not None:
+        chain.append(last_incr)
+    return chain
+
+
+def _is_directory_path(path: str) -> bool:
+    return os.path.isdir(os.path.join(os.sep, path))
+
+
+def _looks_like_directory(path: str) -> bool:
+    if not path:
+        return False
+    normalized = path.rstrip(os.sep)
+    if not normalized:
+        return True
+    if path.endswith(os.sep):
+        return True
+    base = os.path.basename(normalized)
+    _, ext = os.path.splitext(base)
+    return ext == ""
+
+
+def _treat_as_directory(path: str) -> bool:
+    if _is_directory_path(path):
+        return True
+    if _looks_like_directory(path):
+        logger.debug("Treating restore path '%s' as directory (heuristic).", path)
+        return True
+    return False
+
+def _format_chain_item(
+    catalog_no: int,
+    info_by_no: Dict[int, Tuple[datetime, str]],
+    status: str,
+) -> str:
+    info = info_by_no.get(catalog_no)
+    if info:
+        dt, archive_type = info
+        return f"#{catalog_no} {archive_type}@{dt} [{status}]"
+    return f"#{catalog_no} [unknown] [{status}]"
+
+
+def _describe_archive(
+    catalog_no: int,
+    archive_map: Dict[int, str],
+    info_by_no: Dict[int, Tuple[datetime, str]],
+) -> str:
+    archive_path = archive_map.get(catalog_no)
+    base = os.path.basename(archive_path) if archive_path else "unknown"
+    info = info_by_no.get(catalog_no)
+    if info:
+        dt, archive_type = info
+        dt_str = dt.strftime("%Y-%m-%d %H:%M:%S")
+        return f"#{catalog_no} {archive_type}@{dt_str} {base}"
+    return f"#{catalog_no} {base}"
+
+
+def _missing_chain_elements(chain: List[int], archive_map: Dict[int, str]) -> List[str]:
+    missing = []
+    for catalog_no in chain:
+        archive_path = archive_map.get(catalog_no)
+        if not archive_path:
+            missing.append(f"catalog #{catalog_no} missing from archive map")
+            continue
+        slice_path = f"{archive_path}.1.dar"
+        if not os.path.exists(slice_path):
+            missing.append(slice_path)
+    return missing
+
+
+def _pitr_chain_report(
+    backup_def: str,
+    paths: List[str],
+    when: str,
+    config_settings: ConfigSettings,
+) -> int:
+    """
+    Report the PITR archive chain that would be used for a restore at `when`,
+    without performing any restore actions. Returns non-zero if required
+    archives are missing or no chain/candidates can be determined.
+    """
+    if not when:
+        logger.error("PITR report requires --when.")
+        return 1
+
+    parsed_date = _parse_when(when)
+    if not parsed_date:
+        logger.error(f"Could not parse date: '{when}'")
+        return 1
+
+    database = f"{backup_def}{DB_SUFFIX}"
+    database_path = os.path.join(get_db_dir(config_settings), database)
+    timeout = _coerce_timeout(getattr(config_settings, "command_timeout_secs", None))
+    list_result = runner.run(['dar_manager', '--base', database_path, '--list'], timeout=timeout)
+    archive_map = _parse_archive_map(list_result.stdout)
+    if not archive_map:
+        logger.error("Could not determine archive list from dar_manager output.")
+        return 1
+
+    archive_info = _parse_archive_info(archive_map)
+    info_by_no = {catalog_no: (dt, archive_type) for catalog_no, dt, archive_type in archive_info}
+    failures = 0
+    successes = 0
+
+    for path in paths:
+        if _treat_as_directory(path):
+            chain = _select_archive_chain(archive_info, parsed_date)
+            if not chain:
+                logger.error(f"No FULL archive found at or before {parsed_date} for '{path}'")
+                failures += 1
+                continue
+            missing = []
+            chain_display_parts = []
+            for catalog_no in chain:
+                archive_path = archive_map.get(catalog_no)
+                status = "ok"
+                if not archive_path:
+                    status = "missing"
+                    missing.append(f"catalog #{catalog_no} missing from archive map")
+                else:
+                    slice_path = f"{archive_path}.1.dar"
+                    if not os.path.exists(slice_path):
+                        status = "missing"
+                        missing.append(slice_path)
+                chain_display_parts.append(_format_chain_item(catalog_no, info_by_no, status))
+            chain_display = ", ".join(chain_display_parts)
+            logger.info("PITR chain report for '%s': %s", path, chain_display)
+            if missing:
+                for item in missing:
+                    logger.error("PITR chain report missing archive: %s", item)
+                failures += 1
+            else:
+                successes += 1
+            continue
+
+        file_result = runner.run(['dar_manager', '--base', database_path, '-f', path], timeout=timeout)
+        versions = _parse_file_versions(file_result.stdout)
+        candidates = [(num, dt) for num, dt in versions if dt <= parsed_date]
+        candidates.sort(key=lambda item: item[1], reverse=True)
+        logger.info(
+            "PITR chain report candidates for '%s': %s",
+            path,
+            ", ".join(f"#{num}@{dt}" for num, dt in candidates) or "<none>",
+        )
+        if not candidates:
+            logger.error(f"No archive version found for '{path}' at or before {parsed_date}")
+            failures += 1
+            continue
+        catalog_no, dt = candidates[0]
+        archive_path = archive_map.get(catalog_no)
+        if not archive_path:
+            logger.error("PITR chain report missing archive map entry for #%d (%s)", catalog_no, path)
+            failures += 1
+            continue
+        slice_path = f"{archive_path}.1.dar"
+        if not os.path.exists(slice_path):
+            logger.error("PITR chain report missing archive slice: %s", slice_path)
+            failures += 1
+            continue
+        logger.info("PITR chain report selected archive #%d (%s) for '%s'.", catalog_no, dt, path)
+        successes += 1
+
+    logger.info("PITR chain report summary: %d ok, %d failed.", successes, failures)
+    return 0 if failures == 0 else 1
+
+
+def _parse_file_versions(file_output: str) -> List[Tuple[int, datetime]]:
+    versions: List[Tuple[int, datetime]] = []
+    for line in file_output.splitlines():
+        stripped = line.strip()
+        if not stripped:
+            continue
+        match = re.match(r"^(\d+)\s+([A-Za-z]{3}\s+[A-Za-z]{3}\s+\d+\s+\d{2}:\d{2}:\d{2}\s+\d{4})", stripped)
+        if not match:
+            continue
+        try:
+            catalog_no = int(match.group(1))
+            dt = datetime.strptime(match.group(2), "%a %b %d %H:%M:%S %Y")
+        except Exception:
+            continue
+        versions.append((catalog_no, dt))
+    return versions
+
+
+def _guess_darrc_path(config_settings: ConfigSettings) -> Optional[str]:
+    config_dir = os.path.dirname(config_settings.config_file)
+    candidate = os.path.join(config_dir, ".darrc")
+    if os.path.exists(candidate):
+        return candidate
+    script_dir = os.path.dirname(os.path.realpath(__file__))
+    fallback = os.path.join(script_dir, ".darrc")
+    if os.path.exists(fallback):
+        return fallback
+    return None
+
+
+def _restore_with_dar(backup_def: str, paths: List[str], when_dt: datetime, target: str, config_settings: ConfigSettings) -> int:
+    """
+    Restore specific paths by selecting the best matching archive (<= when_dt)
+    using dar_manager metadata, then invoking dar directly.
+
+    This is a fallback for PITR when dar_manager reports that nothing could be
+    restored for a dated request. It inspects the catalog to choose an archive
+    for each path and restores into the provided target directory.
+    """
+    database = f"{backup_def}{DB_SUFFIX}"
+    database_path = os.path.join(get_db_dir(config_settings), database)
+    timeout = _coerce_timeout(getattr(config_settings, "command_timeout_secs", None))
+    list_result = runner.run(['dar_manager', '--base', database_path, '--list'], timeout=timeout)
+    archive_map = _parse_archive_map(list_result.stdout)
+    if not archive_map:
+        logger.error("Could not determine archive list from dar_manager output.")
+        return 1
+    logger.debug("PITR archive map: %s", ", ".join(f"#{k}={v}" for k, v in sorted(archive_map.items())))
+    archive_info = _parse_archive_info(archive_map)
+    info_by_no = {catalog_no: (dt, archive_type) for catalog_no, dt, archive_type in archive_info}
+
+    darrc_path = _guess_darrc_path(config_settings)
+    failures = 0
+    successes = 0
+    missing_archives = set()
+
+    for path in paths:
+        file_result = runner.run(['dar_manager', '--base', database_path, '-f', path], timeout=timeout)
+        if _treat_as_directory(path):
+            chain = _select_archive_chain(archive_info, when_dt)
+            if not chain:
+                logger.error(f"No FULL archive found at or before {when_dt} for '{path}'")
+                failures += 1
+                continue
+            missing = _missing_chain_elements(chain, archive_map)
+            if missing:
+                for item in missing:
+                    missing_archives.add(item)
+                    logger.error("PITR restore missing archive in chain for '%s': %s", path, item)
+                failures += 1
+                continue
+            logger.info(
+                "PITR restore directory '%s' using archive chain: %s",
+                path,
+                ", ".join(_describe_archive(num, archive_map, info_by_no) for num in chain),
+            )
+            restored = True
+            for catalog_no in chain:
+                archive_path = archive_map.get(catalog_no)
+                if not archive_path:
+                    missing_archives.add(f"catalog #{catalog_no} missing from archive map")
+                    logger.error(f"Archive number {catalog_no} missing from archive list; cannot restore '{path}'.")
+                    restored = False
+                    break
+                if not os.path.exists(f"{archive_path}.1.dar"):
+                    missing_archives.add(f"{archive_path}.1.dar")
+                    logger.error(f"Archive slice missing for '{archive_path}.1.dar', cannot complete restore.")
+                    restored = False
+                    break
+                cmd = ['dar', '-x', archive_path, '-wa', '-g', path, '--noconf', '-Q']
+                if target:
+                    cmd.extend(['-R', target])
+                if darrc_path:
+                    cmd.extend(['-B', darrc_path, 'restore-options'])
+                logger.info(
+                    "Applying archive %s for '%s'.",
+                    _describe_archive(catalog_no, archive_map, info_by_no),
+                    path,
+                )
+                result = runner.run(cmd, timeout=timeout)
+                if result.returncode != 0:
+                    logger.error(f"dar restore failed for '{path}' from '{archive_path}': {result.stderr}")
+                    restored = False
+                    break
+            if restored:
+                successes += 1
+            else:
+                failures += 1
+            continue
+
+        versions = _parse_file_versions(file_result.stdout)
+        candidates = [(num, dt) for num, dt in versions if dt <= when_dt]
+        candidates.sort(key=lambda item: item[1], reverse=True)
+        logger.debug(
+            "PITR candidates for '%s': %s",
+            path,
+            ", ".join(f"#{num}@{dt}" for num, dt in candidates) or "<none>",
+        )
+        if not candidates:
+            logger.error(f"No archive version found for '{path}' at or before {when_dt}")
+            failures += 1
+            continue
+
+        restored = False
+        for catalog_no, dt in candidates:
+            archive_path = archive_map.get(catalog_no)
+            if not archive_path:
+                missing_archives.add(f"catalog #{catalog_no} missing from archive map")
+                logger.error(f"Archive number {catalog_no} missing from archive list; cannot restore '{path}'.")
+                restored = False
+                break
+            if not os.path.exists(f"{archive_path}.1.dar"):
+                missing_archives.add(f"{archive_path}.1.dar")
+                logger.error(f"Archive slice missing for '{archive_path}.1.dar', cannot restore '{path}'.")
+                restored = False
+                break
+            logger.info(
+                "PITR restore file '%s' using archive %s.",
+                path,
+                _describe_archive(catalog_no, archive_map, info_by_no),
+            )
+            cmd = ['dar', '-x', archive_path, '-wa', '-g', path, '--noconf', '-Q']
+            if target:
+                cmd.extend(['-R', target])
+            if darrc_path:
+                cmd.extend(['-B', darrc_path, 'restore-options'])
+            logger.info(
+                "Restoring '%s' from archive %s using dar.",
+                path,
+                _describe_archive(catalog_no, archive_map, info_by_no),
+            )
+            result = runner.run(cmd, timeout=timeout)
+            if result.returncode == 0:
+                restored = True
+                successes += 1
+                break
+            logger.error(f"dar restore failed for '{path}' from '{archive_path}': {result.stderr}")
+
+        if not restored:
+            failures += 1
+
+    logger.info("PITR restore summary: %d succeeded, %d failed.", successes, failures)
+    if missing_archives:
+        missing_list = sorted(missing_archives)
+        sample = ", ".join(missing_list[:3])
+        extra = f" (+{len(missing_list) - 3} more)" if len(missing_list) > 3 else ""
+        logger.error("Missing archives detected during PITR restore: %s%s", sample, extra)
+        ts = datetime.now().strftime("%Y-%m-%d %H:%M")
+        send_discord_message(
+            f"{ts} - manager: PITR restore missing archives ({len(missing_list)} missing).",
+            config_settings=config_settings,
+        )
+    if failures:
+        ts = datetime.now().strftime("%Y-%m-%d %H:%M")
+        send_discord_message(
+            f"{ts} - manager: PITR restore completed with failures ({failures} failed, {successes} succeeded).",
+            config_settings=config_settings,
+        )
+    return 0 if failures == 0 else 1
+
+
 def add_specific_archive(archive: str, config_settings: ConfigSettings, directory: str = None) -> int:
     """
     Adds the specified archive to its catalog database. Prompts for confirmation if it's older than existing entries.
@@ -573,27 +1263,30 @@ def add_directory(args: argparse.ArgumentParser, config_settings: ConfigSettings
     dar_pattern = re.compile(r'^(.*?_(FULL|DIFF|INCR)_(\d{4}-\d{2}-\d{2}))\.1.dar$') # just read slice #1 of an archive
     # List of DAR archives with their dates and base names
     dar_archives = []
+    type_order = {"FULL": 0, "DIFF": 1, "INCR": 2}
 
     for filename in os.listdir(args.add_dir):
         logger.debug(f"check if '{filename}' is a dar archive slice #1?")
         match = dar_pattern.match(filename)
         if match:
             base_name = match.group(1)
+            archive_type = match.group(2)
             date_str = match.group(3)
             date_obj = datetime.strptime(date_str, '%Y-%m-%d')
-            dar_archives.append((date_obj, base_name))
-            logger.debug(f" -> yes: base name: {base_name}, date: {date_str}")
+            dar_archives.append((date_obj, type_order.get(archive_type, 99), base_name, archive_type))
+            logger.debug(f" -> yes: base name: {base_name}, type: {archive_type}, date: {date_str}")
 
     if not dar_archives or len(dar_archives) == 0:
         logger.info(f"No 'dar' archives found in directory {args.add_dir}")
         return
 
-    # Sort the DAR archives by date
+    # Sort the DAR archives by date then type (FULL -> DIFF -> INCR) to avoid interactive ordering prompts.
     dar_archives.sort()
+    logger.debug("Sorted archives for add-dir: %s", [(d.strftime("%Y-%m-%d"), t, n) for d, t, n, _ in dar_archives])
 
     # Loop over the sorted DAR archives and process them
     result: List[Dict] = []
-    for date_obj, base_name in dar_archives:
+    for _date_obj, _type_order, base_name, _archive_type in dar_archives:
         logger.info(f"Adding dar archive: '{base_name}' to it's catalog database")
         result_archive = add_specific_archive(base_name, config_settings, args.add_dir)
         result.append({ f"{base_name}" : result_archive})
@@ -657,7 +1350,8 @@ def remove_specific_archive(archive: str, config_settings: ConfigSettings) -> in
     cat_no:int = cat_no_for_name(archive, config_settings)
     if cat_no >= 0:
         command = ['dar_manager', '--base', database_path, "--delete", str(cat_no)]
-        process: CommandResult = runner.run(command)
+        timeout = _coerce_timeout(getattr(config_settings, "command_timeout_secs", None))
+        process: CommandResult = runner.run(command, timeout=timeout)
         logger.info(f"CommandResult: {process}")
     else:
         logger.warning(f"archive: '{archive}' not found in it's catalog database: {database_path}")
@@ -684,6 +1378,26 @@ def build_arg_parser():
     parser.add_argument('-l', '--list-catalogs', action='store_true', help='List catalogs in databases for all backup definitions')
     parser.add_argument('--list-archive-contents', type=str, help="List contents of the archive's catalog. Argument is the archive name.").completer = archive_content_completer
     parser.add_argument('--find-file', type=str, help="List catalogs containing <path>/file. '-d <definition>' argument is also required")
+    parser.add_argument('--restore-path', nargs='+', help="Restore specific path(s) (Point-in-Time Recovery).")
+    parser.add_argument('--when', type=str, help="Date/time for restoration (used with --restore-path).")
+    parser.add_argument('--target', type=str, default=None, help="Target directory for restoration (default: current dir).")
+    parser.add_argument('--pitr-report', action='store_true', help="Report PITR archive chain for --restore-path/--when without restoring.")
+    parser.add_argument(
+        '--pitr-report-first',
+        action='store_true',
+        help="Run PITR chain report before restore and abort if missing archives.",
+    )
+    parser.add_argument(
+        '--relocate-archive-path',
+        nargs=2,
+        metavar=("OLD", "NEW"),
+        help="Rewrite archive path prefix in the catalog DB (requires --backup-def).",
+    )
+    parser.add_argument(
+        '--relocate-archive-path-dry-run',
+        action='store_true',
+        help="Show archive path changes without applying them (use with --relocate-archive-path).",
+    )
     parser.add_argument('--verbose', action='store_true', help='Be more verbose')
     parser.add_argument('--log-level', type=str, help="`debug` or `trace`, default is `info`", default="info")
     parser.add_argument('--log-stdout', action='store_true', help='also print log messages to stdout')
@@ -739,6 +1453,7 @@ def main():
         return
 
     command_output_log = config_settings.logfile_location.replace("dar-backup.log", "dar-backup-commands.log")
+    trace_log_file = derive_trace_log_path(config_settings.logfile_location)
     logger = setup_logging(
         config_settings.logfile_location,
         command_output_log,
@@ -746,6 +1461,7 @@ def main():
         args.log_stdout,
         logfile_max_bytes=config_settings.logfile_max_bytes,
         logfile_backup_count=config_settings.logfile_backup_count,
+        trace_log_file=trace_log_file,
         trace_log_max_bytes=getattr(config_settings, "trace_log_max_bytes", 10485760),
         trace_log_backup_count=getattr(config_settings, "trace_log_backup_count", 1)
     )
@@ -753,6 +1469,7 @@ def main():
     runner = CommandRunner(
         logger=logger,
         command_logger=command_logger,
+        default_timeout=getattr(config_settings, "command_timeout_secs", 30) or 30,
         default_capture_limit_bytes=getattr(config_settings, "command_capture_max_bytes", None)
     )
 
@@ -767,10 +1484,12 @@ def main():
     start_msgs.append(("Config file:", args.config_file))
     args.verbose and start_msgs.append(("Backup dir:", config_settings.backup_dir))
     start_msgs.append(("Logfile:", config_settings.logfile_location))
+    args.verbose and start_msgs.append(("Trace log:", trace_log_file))
     args.verbose and start_msgs.append(("Logfile max size (bytes):", config_settings.logfile_max_bytes))
     args.verbose and start_msgs.append(("Logfile backup count:", config_settings.logfile_backup_count))
     args.verbose and start_msgs.append(("--alternate-archive-dir:", args.alternate_archive_dir))
     args.verbose and start_msgs.append(("--remove-specific-archive:", args.remove_specific_archive)) 
+    args.verbose and start_msgs.append(("--relocate-archive-path:", args.relocate_archive_path))
     dar_manager_properties = get_binary_info(command='dar_manager')
     start_msgs.append(("dar_manager:", dar_manager_properties['path']))
     start_msgs.append(("dar_manager v.:", dar_manager_properties['version']))
@@ -804,7 +1523,7 @@ def main():
         return
 
     if args.backup_def and not args.backup_def.strip():
-        logger.error(f"No backup definition given to --backup-def")
+        logger.error("No backup definition given to --backup-def")
         sys.exit(1)
         return
 
@@ -816,12 +1535,46 @@ def main():
             return
 
     if args.list_archive_contents and not args.list_archive_contents.strip():
-        logger.error(f"--list-archive-contents <param> not given, exiting")
+        logger.error("--list-archive-contents <param> not given, exiting")
+        sys.exit(1)
+        return
+
+    if args.relocate_archive_path and not args.backup_def:
+        logger.error("--relocate-archive-path requires the --backup-def, exiting")
+        sys.exit(1)
+        return
+
+    if args.relocate_archive_path_dry_run and not args.relocate_archive_path:
+        logger.error("--relocate-archive-path-dry-run requires --relocate-archive-path, exiting")
         sys.exit(1)
         return
 
     if args.find_file and not args.backup_def:
-        logger.error(f"--find-file requires the --backup-def, exiting")
+        logger.error("--find-file requires the --backup-def, exiting")
+        sys.exit(1)
+        return
+
+    if args.restore_path and not args.backup_def:
+        logger.error("--restore-path requires the --backup-def, exiting")
+        sys.exit(1)
+
+    if args.restore_path and not args.target and not args.pitr_report:
+        logger.error("--restore-path requires the --target directory, exiting")
+        sys.exit(1)
+        return
+
+    if args.pitr_report:
+        if not args.restore_path:
+            logger.error("--pitr-report requires --restore-path, exiting")
+            sys.exit(1)
+            return
+        if not args.when:
+            logger.error("--pitr-report requires --when, exiting")
+            sys.exit(1)
+            return
+
+    if args.pitr_report_first and not args.restore_path:
+        logger.error("--pitr-report-first requires --restore-path, exiting")
         sys.exit(1)
         return
 
@@ -879,11 +1632,40 @@ def main():
             sys.exit(result)
             return
 
+        if args.relocate_archive_path:
+            old_prefix, new_prefix = args.relocate_archive_path
+            result = relocate_archive_paths(
+                args.backup_def,
+                old_prefix,
+                new_prefix,
+                config_settings,
+                dry_run=args.relocate_archive_path_dry_run,
+            )
+            sys.exit(result)
+            return
+
 
         if args.find_file:
             result = find_file(args.find_file, args.backup_def, config_settings)
             sys.exit(result)
             return
+            
+        if args.pitr_report:
+            result = _pitr_chain_report(args.backup_def, args.restore_path, args.when, config_settings)
+            sys.exit(result)
+            return
+
+        if args.restore_path:
+            if args.pitr_report_first:
+                report_when = args.when or "now"
+                result = _pitr_chain_report(args.backup_def, args.restore_path, report_when, config_settings)
+                if result != 0:
+                    sys.exit(result)
+                    return
+            result = restore_at(args.backup_def, args.restore_path, args.when, args.target, config_settings, verbose=args.verbose)
+            sys.exit(result)
+            return
+
     except Exception as e:
         msg = f"Unexpected error during manager operation: {e}"
         logger.error(msg, exc_info=True)