# Danielfm Workstation Backup Role

This role configures the backup jobs I use in my workstations using Restic.

## Requirements

Nothing.

## Role Variables

Available variables are listed below, along with default values.

**Restic configuration directory:**
```yaml
backup_restic_config_dir: '$HOME/.config/restic'
```

Directory where restic configuration files, scripts, and password files are stored.

**List of Restic repositories:**

```yaml
backup_restic_repositories: []
```

Each repository can have the following properties:
- `name`: Repository identifier (required)
- `repository`: Repository path or URL (required)
- `password_file`: Custom password file name (optional, defaults to global `backup_restic_password_file`)
- `password_command`: Custom password command (optional, defaults to global `backup_restic_password_command`)
- `extra_excludes`: List of additional exclude patterns specific to this repository (optional, additive to global excludes)

Example:
```yaml
backup_restic_repositories:
  - name: local
    repository: /media/user/backup-vol/restic
  - name: hetzner
    repository: 'sftp:<user>@<host>:<dir>'
    extra_excludes:
      - 'large_files/'
      - '*.iso'
  - name: s3
    repository: 's3:s3.us-east-1.amazonaws.com/<bucket>/<dir>'
    password_file: 'remote-passwd'
    password_command: 'pass show backup/remote-restic'
    extra_excludes:
      - 'Videos/'
      - '*.mp4'
```

Source directories backed up by Restic:

```yaml
backup_restic_source_directories:
  - '$HOME'
```

**Exclude patterns:**

```yaml
backup_restic_extra_patterns: []
backup_restic_extra_excludes: []
```

The `backup_restic_extra_excludes` list defines global exclude patterns that apply
to all repositories. These patterns are added to a base set of common excludes
(cache directories, build artifacts, logs, etc.) in `~/.config/restic/excludes.txt`.

**Repository-specific excludes:**

Individual repositories can define their own additional exclude patterns using the
`extra_excludes` property. When configured, these patterns are written to a separate
exclude file (`~/.config/restic/excludes-<repo>.txt`) and applied in addition to
the global excludes. This allows you to exclude specific content from certain
repositories without affecting others.

For example, you might want to exclude large video files from your cloud backup
but include them in your local backup:

```yaml
backup_restic_repositories:
  - name: local
    repository: /media/backup/restic
  - name: cloud
    repository: 's3:s3.amazonaws.com/bucket/path'
    extra_excludes:
      - 'Videos/'
      - '*.mp4'
      - '*.mkv'
```

**Global Restic password options (used as defaults for repositories):**

```yaml
backup_restic_password_file: 'passwd'
backup_restic_password_command: ''
```

The `backup_restic_password_file` specifies the default filename for the
password file (relative to the restic config directory). The role will
automatically create an empty password file with 0600 permissions if it doesn't
exist (only when not using `password_command`). You must manually populate this
file with your restic repository password.

The `backup_restic_password_command` is optional and allows specifying a
default command to retrieve the password dynamically. When set, it takes
precedence over the password file and no password file will be created.

These global settings are used as fallbacks when repositories don't specify
their own `password_file` or `password_command` options:
- If a repository doesn't specify `password_command`, the global `backup_restic_password_command` is used (if set)
- If neither the repository nor global `password_command` is set, password files are used
- Repository-specific password files will be created automatically if configured

**Retention settings:**
```yaml
backup_restic_keep_daily: 7
backup_restic_keep_weekly: 4
backup_restic_keep_monthly: 6
backup_restic_keep_yearly: 1
```

**Backup schedule settings:**
```yaml
backup_restic_schedule: 'daily'
backup_restic_randomized_delay: '10m'
```

**Prune schedule settings:**
```yaml
backup_restic_prune_schedule: 'weekly'
backup_restic_prune_randomized_delay: '1h'
```

## Architecture

This role creates separate systemd services and timers for each configured
repository, providing better reliability and isolation. If one repository
becomes unavailable, backups to other repositories will continue to work.

For each repository named `<repo>`, the following systemd units are created:
- `restic-backup@<repo>.service` - Backup service for the repository
- `restic-backup@<repo>.timer` - Timer to schedule backups
- `restic-prune@<repo>.service` - Prune service for the repository
- `restic-prune@<repo>.timer` - Timer to schedule pruning operations

Each repository gets its own backup, prune, and mount scripts in
`~/.config/restic/scripts/`.

## Mounting Backups

For each configured repository, a mount script is generated that allows you to
browse and restore files from your backups. The mount scripts are located at:
`~/.config/restic/scripts/mount-<repo>.sh`

Usage:
```bash
# Mount to default location (~/.config/restic/mounts/<repo>)
~/.config/restic/scripts/mount-local.sh

# Mount to custom location
~/.config/restic/scripts/mount-local.sh /tmp/my-backup

# Unmount
fusermount -u ~/.config/restic/mounts/<repo>
```

The mounted filesystem provides access to all snapshots through multiple views:
- `snapshots/` - Browse snapshots by date and time
- `hosts/` - Browse snapshots by hostname
- `tags/` - Browse snapshots by tags
- `ids/` - Browse snapshots by their unique IDs

## Dependencies

None.

## Example Playbook

``` yaml
- hosts: servers
  vars:
    backup_restic_repositories:
      - name: local
        repository: '/media/<user>/<vol>/<path>'
      - name: remote
        repository: 's3:s3.us-east-1.amazonaws.com/<bucket>/<path>'
        password_command: 'pass show backup/remote-restic'

    backup_restic_source_directories:
      - '$HOME'
      - '/etc'

    backup_restic_extra_patterns: []

    backup_restic_extra_excludes:
      - '$HOME/Downloads'

    backup_restic_password_file: 'passwd'
    backup_restic_password_command: 'pass show backup/restic'

    backup_restic_keep_daily: 7
    backup_restic_keep_weekly: 4
    backup_restic_keep_monthly: 6
    backup_restic_keep_yearly: 1

  roles:
    - danielfm.workstation.backup
```

## License

MIT

## Author Information

This role was created by Daniel Martins.
