# Danielfm Workstation Base Role

This role sets up essential base packages and configuration files for
workstations. It provides:

- System timezone and locale configuration
- Essential development and system packages
- Base shell configuration and environment setup
- Git configuration and common ignore patterns
- Systemd user services for backup automation
- QMK keyboard firmware development support via udev rules

## Requirements

- A Debian-based or Fedora-based Linux system
- Root privileges for system package installation and configuration

## Role Variables

Available variables are listed below, along with default values.

**System timezone configuration:**
```yaml
base_system_timezone: America/Sao_Paulo
```

**System locales to be generated and configured:**
```yaml
base_system_locales:
  - pt_BR.UTF-8
  - en_US.UTF-8
```

**Flatpak remotes configuration:**
```yaml
base_flatpak_remotes:
  - url: https://dl.flathub.org/repo/flathub.flatpakrepo
    method: user
  - url: https://dl.flathub.org/repo/flathub.flatpakrepo
    method: system
```

Configure Flatpak repositories for the base system. Each entry should specify
`url` (repository URL) and `method` (either `user` or `system`).

**Keyring password command:**
```yaml
base_keyring_password_command: 'pass show personal/keyring'
```

Command used to retrieve the GNOME keyring password for automatic unlocking.
This is used in the `unlock-gnome-keyring` script.

**SSH configuration - Additional host entries:**
```yaml
base_ssh_hosts: []
```

Define additional SSH host entries to be added to `~/.ssh/config`. Each entry
should be a dictionary with SSH configuration options:

```yaml
base_ssh_hosts:
  - host: example-server
    hostname: example.com
    user: myuser
    port: 2222
    identity_file: ~/.ssh/example_key
    identities_only: yes
  - host: backup-server
    hostname: backup.example.com
    user: backup
    identity_file: ~/.ssh/backup_key
    forward_agent: yes
```

Supported SSH options include: `hostname`, `user`, `port`, `identity_file`,
`identities_only`, `forward_agent`, `compression`, `server_alive_interval`,
`proxy_command`, `local_forward`, `remote_forward`, and any other SSH
configuration directive (use snake_case for multi-word options).

**Crypttab configuration - Encrypted device setup:**
```yaml
base_crypttab_entries: []
```

Configure crypttab entries for encrypted devices. Each entry should be a dictionary with `name` and `opts` keys:

```yaml
base_crypttab_entries:
  - name: nvme0n1p3_crypt
    opts: discard,keyscript=/usr/share/yubikey-luks/ykluks-keyscript
  - name: sdb1_crypt
    opts: discard,luks
```

- `name`: The name/identifier for the encrypted device mapping
- `opts`: Additional crypttab options (e.g., discard, keyscript, luks, etc.)

Read [this doc](https://wiki.debian.org/Smartcards/YubiKey4) for more
information on how to use your YubiKeys to unlock the LUKS encryption.

**Firewall configuration:**
```yaml
base_firewalld_services:
  - service: ssh
    zone: home
    state: enabled
  - protocol: mdns
    zone: home
    state: enabled

base_firewalld_ports:
  - port: 53317/tcp # Localsend
    zone: home
    state: enabled
  - port: 53317/udp # Localsend
    zone: home
    state: enabled
```

Configure firewalld rules for services and ports. By default, mDNS and SSH
services are enabled for the home zone to support local network service
discovery.

Each entry should specify the rule type and parameters:

```yaml
base_firewalld_services:
  - service: syncthing
    zone: home
    state: enabled
  - service: http
    zone: public
    state: enabled

base_firewalld_ports:
  - port: 8080/tcp
    zone: home
    state: enabled
  - port: 9090/udp
    zone: public
    state: enabled
```

- `service`/`port`: The firewalld service name or port specification
- `zone`: The firewalld zone to apply the rule to (e.g., home, public, work)
- `state`: Either `enabled` or `disabled`

**Default applications configuration:**
```yaml
base_default_app_text_editor: org.xfce.mousepad.desktop
base_default_app_image_viewer: org.xfce.ristretto.desktop
base_default_app_media_player: org.xfce.Parole.desktop
base_default_app_web_browser: org.mozilla.firefox.desktop
base_default_app_file_manager: thunar.desktop
base_default_app_pdf_viewer: firefox.desktop
```

Configure default applications for various MIME types via
`~/.config/mimeapps.list`. Each variable should specify the `.desktop` file
name for the preferred application:

```yaml
base_default_app_text_editor: emacsclient.desktop
base_default_app_image_viewer: eog.desktop
base_default_app_media_player: vlc.desktop
base_default_app_web_browser: google-chrome.desktop
base_default_app_file_manager: org.gnome.Nautilus.desktop
base_default_app_pdf_viewer: evince.desktop
```

These settings control the default applications for:

- **text_editor**: Text files, source code, shell scripts, configuration files (XML, YAML, etc.)
- **image_viewer**: Image files (PNG, JPEG, GIF)
- **media_player**: Audio files (MP3, etc.)
- **web_browser**: HTML files and HTTP/HTTPS URLs
- **file_manager**: Directory navigation
- **pdf_viewer**: PDF documents

## Dependencies

None.

## Example Playbook

```yaml
- hosts: localhost
  connection: local
  vars:
    base_system_timezone: America/Sao_Paulo
    base_system_locales:
      - pt_BR.UTF-8
      - en_US.UTF-8
    base_ssh_hosts:
      - host: production-server
        hostname: prod.example.com
        user: deploy
        identity_file: ~/.ssh/production_key
        identities_only: yes
    base_crypttab_entries:
      - name: nvme0n1p3_crypt
        opts: discard,keyscript=/usr/share/yubikey-luks/ykluks-keyscript
  roles:
    - danielfm.workstation.base
```

## What This Role Configures

**System Configuration:**
- System timezone and locale settings
- Essential packages for development and system administration
- Systemd journal size limits (100M maximum)
- Crypttab entries for encrypted devices (when configured)

**User Environment:**
- Shell environment configuration (`~/.bashrc.d/00-env.sh`)
- Git global configuration and ignore patterns (`~/.config/git/config`, `~/.config/git/ignore`)
- SSH configuration with support for additional host entries (`~/.ssh/config`)
- Nano editor configuration (`~/.nanorc`)

**Services and Automation:**
- Systemd user services for restic backup automation
- Syncthing service enabled for file synchronization
- Restic timer enabled for automated backups

**Hardware Support:**
- QMK keyboard development udev rules (`/etc/udev/rules.d/50-qmk.rules`)

## Important Notes

- The role configures GPG-based SSH authentication via `~/.bashrc.d/00-env.sh`
- Git is pre-configured with signing enabled (requires GPG setup)

## YubiKey U2F Setup

To configure your YubiKey for U2F authentication, use the `pamu2fcfg` command to
generate the required credentials. The `--pin-verification` flag requires the
key PIN for additional security.

**For the first key:**
```bash
pamu2fcfg --pin-verification > ~/.config/Yubico/u2f_keys
```

**For additional keys (append to the file):**
```bash
pamu2fcfg --pin-verification --nouser >> ~/.config/Yubico/u2f_keys
```

After configuring your keys, you can use them for authentication with
PAM-enabled services that support U2F.

## License

MIT

## Author Information

This role was created by Daniel Martins.
