Skip to content

cli-reference.md

Latest commit

 

History

History
246 lines (193 loc) · 12.2 KB

cli-reference.md

File metadata and controls

246 lines (193 loc) · 12.2 KB
Raw

CLI Reference

Back to README

CLI Tools Overview

Command Description
dar-backup Perform full, differential, or incremental backups with verification and restore testing
manager Maintain and query catalog databases for archives
cleanup Remove outdated DIFF/INCR archives (and optionally FULLs)
clean-log Clean up excessive log output from dar command logs
dar-backup-systemd Generate (and optionally install) systemd timers and services for automated backups
installer Set up directories and optionally create catalog databases according to a config file
demo Set up required directories and config files for a demo
dar-backup-dashboard Start Datasette and open the metrics dashboard in the browser

Dar-backup options

This script does backups including par2 redundancy, validation and restoring.

Available options:

-F, --full-backup                    Perform a full backup.
-D, --differential-backup            Perform a differential backup.
-I, --incremental-backup             Perform an incremental backup.
-d, --backup-definition <name>       Specify the backup definition file.
--alternate-reference-archive <file> Use a different archive for DIFF/INCR backups.
-c, --config-file <path>             Specify the path to the configuration file.
--darrc <path>                       Specify an optional path to .darrc.
--examples                           Show examples of using dar-backup.py.
-l, --list                           List available backups.
--list-contents <archive>            List the contents of a specified archive.
--list-definitions                   List backup definitions from BACKUP.D_DIR.
--selection <params>                 Define file selection for listing/restoring.
-r, --restore <archive>              Restore archive.
--restore-dir                        Directory on which to restore
--preserve-ownership                 Force uid/gid restoration for this run (overrides config; root only; mutually exclusive with --ignore-ownership).
--ignore-ownership                   Force uid/gid to be ignored for this run (overrides RESTORE_OWNERSHIP = yes in config; mutually exclusive with --preserve-ownership).
--no-deleted                         Do not process deletion records from DIFF/INCR archives (passes --deleted=ignore to dar). Useful when restoring a DIFF or INCR archive directly to an empty directory without first restoring the FULL.
--verbose                            Enable verbose output.
--suppress-dar-msg                   Filter out this from the darrc: "-vt", "-vs", "-vd", "-vf", "-va"
--log-level <level>                  `debug` or `trace`, default is `info`.
--log-stdout                         Also print log messages to stdout.
--do-not-compare                     Do not compare restores to file system.
--allow-unsafe-definition-names      Disable backup definition name validation (allows underscores or other characters).
--preflight-check                    Run preflight checks and exit (runs automatically; this flag just exits after checks).
--examples                           Show examples of using dar-backup.
--readme                             Print README.md and exit
--readme-pretty                      Print README.md with Markdown styling and exit
--changelog                          Print Changelog and exit
--changelog-pretty                   Print Changelog with Markdown styling and exit
--doc <name>                         Print a documentation file by name and exit (tab completion lists available docs)
--doc-pretty <name>                  Print a documentation file with Markdown styling and exit
-v, --version                         Show version and license information.

Dar-backup exit codes

  • 0: Success.
  • 1: Error (backup/restore/preflight failure).
    • includes an invalid backup-definition name (see naming rules) — as of v2-1.1.10 this is rc=1 whether the invalid name was given explicitly via -d or found while scanning BACKUP.D_DIR for an all-definitions run; previously the latter case was only a warning (rc=2)
  • 2: Warning (restore test failed or backup already exists and is skipped).
  • 127: Typically an error during startup, file or config value missing
    • if the dar -t test fails, exit code 1 is emitted
    • restore tests could fail if the source file has changed after the backup

Dar-backup env vars

Env var Value Description
DAR_BACKUP_CONFIG_FILE Full path to config file Overrides built-in default, overridden by --config-file
DAR_BACKUP_DISCORD_WEBHOOK_URL https://discord.com/api/webhooks/\<userID>/<webhook UUID> The full url
DAR_BACKUP_COMMAND_TIMEOUT_SECS -1 or > 0 Overrides config COMMAND_TIMEOUT_SECS. Use -1 to disable timeouts.

Manager Options

This script manages dar databases and catalogs.

Available options:

-c, --config-file <path>             Path to dar-backup.conf.
--create-db                          Create missing databases for all backup definitions.
--alternate-archive-dir <path>       Use this directory instead of BACKUP_DIR in the config file.
--add-dir <path>                     Add all archive catalogs in this directory to databases.
-d, --backup-def <name>              Restrict operations to this backup definition.
--add-specific-archive <archive>     Add a specific archive to the catalog database.
--remove-specific-archive <archive>  Remove a specific archive from the catalog database.
-l, --list-catalogs                  List catalogs in databases for all backup definitions.
--list-archive-contents <archive>    List the contents of an archive's catalog by archive name.
--find-file <file>                   Search catalogs for a specific file.
--restore-path <path> [<path> ...]   Restore specific path(s) (Point-in-Time Recovery).
--when <timestamp>                   Date/time for restoration (used with --restore-path).
--target <path>                      Target directory for restoration (default: current dir).
--preserve-ownership                 Force uid/gid restoration for this run (overrides config; root only; mutually exclusive with --ignore-ownership).
--ignore-ownership                   Force uid/gid to be ignored for this run (overrides RESTORE_OWNERSHIP = yes in config; mutually exclusive with --preserve-ownership).
--no-deleted                         Do not process deletion records from DIFF/INCR archives (passes --deleted=ignore to dar). Useful when restoring a DIFF or INCR archive directly to an empty directory.
--pitr-report                        Report PITR archive chain for --restore-path/--when without restoring.
--pitr-report-first                  Run PITR chain report before restore and abort if missing archives.
--relocate-archive-path <old> <new>  Rewrite archive path prefix in the catalog DB (requires --backup-def).
--relocate-archive-path-dry-run      Show archive path changes without applying them (use with --relocate-archive-path).
--verbose                            Enable verbose output.
--log-level <level>                  Set log level (`debug` or `trace`, default is `info`).
--log-stdout                         Also print log messages to stdout.

Manager env vars

Env var Value Description
DAR_BACKUP_CONFIG_FILE path to the config file Default is $HOME/.config/dar-backup/dar-backup.conf
DAR_BACKUP_COMMAND_TIMEOUT_SECS -1 or > 0 Overrides config COMMAND_TIMEOUT_SECS. Use -1 to disable timeouts.

Cleanup options

This script removes old backups and par2 files according to [AGE] settings in config file.

Catalogs in catalog databases are also removed.

Supported options:

-d, --backup-definition                           Backup definition to cleanup.
-c, --config-file                                 Path to 'dar-backup.conf'
-v, --version                                     Show version & license information.
--alternate-archive-dir                           Clean up in this directory instead of the default one.
--cleanup-specific-archives "<archive>, <>, ..."  Comma separated list of archives to cleanup.
-l, --list                                       List available archives (filter using the -d option).
--dry-run                                        Show what would be deleted without removing files.
--verbose                                         Print various status messages to screen.
--log-level <level>                               `debug` or `trace`, default is `info`", default="info".
--log-stdout                                      Print log messages to stdout.
--test-mode                                       This is used when running pytest test cases

Cleanup env vars

Env var Value Description
DAR_BACKUP_CONFIG_FILE path to the config file Default is $HOME/.config/dar-backup/dar-backup.conf
DAR_BACKUP_COMMAND_TIMEOUT_SECS -1 or > 0 Overrides config COMMAND_TIMEOUT_SECS. Use -1 to disable timeouts.

Clean-log options

This script removes excessive logging output from dar logs, improving readability and efficiency. Available options:

-f, --file <path>          Specify the log file(s) to be cleaned.
-c, --config-file <path>   Path to dar-backup.conf.
--dry-run                  Show which lines would be removed without modifying the file.
-v, --version              Display version and licensing information.
-h, --help                 Displays usage info

Dar-backup-systemd options

Generates and optionally install systemd user service units and timers.

-h, --help           Show this help message and exit
--venv VENV          Path to the Python venv with dar-backup
--dar-path DAR_PATH  Optional path to dar binary's directory
--install            Install the units to ~/.config/systemd/user

Installer options

Sets up dar-backup according to provided config file.

The installer creates the necessary backup catalog databases if --create-db is given.

--config                 Path to a config file. The configured directories will be created.
--create-db              Create backup catalog databases. Use this option with `--config`.
--install-autocompletion Add bash or zsh auto completion - idempotent.
--remove-autocompletion  Remove the auto completion from bash or zsh.
-v, --version            Display version and licensing information.
-h, --help               Displays usage info.

Demo options

Sets up dar-backup in a demo configuration.

It is non-destructive and stops if directories are already in place.

Create directories:

  • ~/.config/dar-backup/
    • ~/.config/dar-backup/backup.d/
  • ~/dar-backup/
    • ~/dar-backup/backups/
    • ~/dar-backup/restore/

Sets up demo config files:

  • ~/.config/dar-backup/dar-backup.conf
  • ~/.config/dar-backup/backup.d/demo
-i, --install       Sets up `dar-backup`.
--root-dir          Specify the root directory for the backup.
--dir-to-backup     Directory to backup, relative to the root directory.
--backup-dir        Directory where backups and redundancy files are put.
--override          By default, the script will not overwrite existing files or directories.
                    Use this option to override this behavior.
--generate          Generate config files and put them in /tmp/ for inspection
                    without writing to $HOME.
-v, --version       Display version and licensing information.
-h, --help          Displays usage info

Dar-backup-dashboard options

Start Datasette and open the metrics dashboard in the browser.

--db PATH          Path to the metrics database.
                   Overrides METRICS_DB_PATH from the config file.
-c / --config-file PATH
                   Path to dar-backup.conf.
                   Default: $DAR_BACKUP_CONFIG_FILE or
                   ~/.config/dar-backup/dar-backup.conf
--port PORT        Preferred Datasette port (default: 8001).
                   A nearby free port is used automatically if taken.
--no-browser       Start Datasette but do not open a browser window.
                   Prints the dashboard URL to stdout instead.