$ sudo apt install btrfs-progs smartmontools

# 1. Check the state of the disks BEFORE using them, even new ones
$ sudo smartctl -a /dev/sda | grep -E 'Model|Power_On_Hours|Reallocated'
Device Model:     WDC WD80EFPX-68C4ZN0
  9 Power_On_Hours          0x0032   100   100   000    Old_age   Always  -  4
  5 Reallocated_Sector_Ct   0x0033   100   100   140    Pre-fail  Always  -  0

# 2. Create the filesystem in RAID 1 (data AND metadata)
$ sudo mkfs.btrfs -L media -d raid1 -m raid1 /dev/sda /dev/sdb
Label:              media
UUID:               8f3a2c11-4d5e-4a91-b7c2-1e9d0f8a3b45
Number of devices:  2
Data,RAID1:  8.00TiB
Metadata,RAID1: 8.00GiB

# 3. Mount by UUID, never by /dev/sdX (05-04)
$ sudo mkdir -p /srv/media
$ blkid /dev/sda | grep -oP 'UUID="\K[^"]+'
8f3a2c11-4d5e-4a91-b7c2-1e9d0f8a3b45

# /etc/fstab
# compress=zstd:3  -> compresses what is compressible; already compressed
#                     video is detected and skipped, so it costs nothing
# noatime          -> do not write the access time on every read:
#                     fewer writes and a longer disk life
# nofail           -> IF THE DISK IS NOT THERE, THE SYSTEM STILL BOOTS.
#                     Without this, a disconnected disk leaves the machine
#                     in emergency mode, with no network and no SSH: you
#                     have to go there with a keyboard and a monitor. At
#                     home, essential.
# x-systemd.device-timeout=10 -> do not wait 90 s for an absent disk
UUID=8f3a2c11-4d5e-4a91-b7c2-1e9d0f8a3b45  /srv/media  btrfs \
  defaults,compress=zstd:3,noatime,nofail,x-systemd.device-timeout=10  0  0

$ sudo mount -a          # ALWAYS after touching fstab (course convention)
$ findmnt /srv/media
TARGET     SOURCE    FSTYPE OPTIONS
/srv/media /dev/sda  btrfs  rw,noatime,compress=zstd:3,nofail

$ sudo btrfs filesystem usage /srv/media
Overall:
    Device size:                  14.55TiB
    Device allocated:              2.02TiB
    Used:                          2.01TiB
    Free (estimated):              6.26TiB      (min: 6.26TiB)
Data,RAID1: Size:1.01TiB, Used:1.00TiB
   /dev/sda	 1.01TiB
   /dev/sdb	 1.01TiB

# Verifies ALL the checksums and repairs what it can from the other copy
$ sudo btrfs scrub start -B /srv/media
scrub done for 8f3a2c11-4d5e-4a91-b7c2-1e9d0f8a3b45
	Total to scrub: 2.01TiB
	Rate: 178.42MiB/s
	Error summary: csum=2
	  Corrected: 2
	  Uncorrectable: 0

# /etc/systemd/system/btrfs-scrub.timer
[Unit]
Description=Monthly Btrfs scrub of /srv/media

[Timer]
OnCalendar=Sun *-*-01..07 03:00:00   # first Sunday of each month
Persistent=true
RandomizedDelaySec=1h

[Install]
WantedBy=timers.target

# /etc/systemd/system/btrfs-scrub.service
[Unit]
Description=Btrfs scrub

[Service]
Type=oneshot
ExecStart=/usr/bin/btrfs scrub start -B -c idle -n 5 /srv/media
# -c idle -n 5: lowest I/O priority, so as not to disturb anybody who is
# watching a film at three in the morning
Nice=19
IOSchedulingClass=idle

$ sudo install -m 0755 -d /etc/apt/keyrings
$ curl -fsSL https://repo.jellyfin.org/jellyfin_team.gpg.key | \
      sudo gpg --dearmor -o /etc/apt/keyrings/jellyfin.gpg
$ sudo chmod 0644 /etc/apt/keyrings/jellyfin.gpg

$ cat <<EOF | sudo tee /etc/apt/sources.list.d/jellyfin.sources
Types: deb
URIs: https://repo.jellyfin.org/ubuntu
Suites: noble
Components: main
Architectures: amd64
Signed-By: /etc/apt/keyrings/jellyfin.gpg
EOF

$ sudo apt update && sudo apt install jellyfin
$ systemctl is-active jellyfin
active

$ gpg --show-keys /etc/apt/keyrings/jellyfin.gpg | head -2
pub   rsa4096 2018-11-08 [SC]
      04B7DA6B1FE10D5E76D9D5A6F5B2F0D5A8E5D6C3

$ sudo systemctl edit jellyfin

# /etc/systemd/system/jellyfin.service.d/override.conf
[Service]
# --- Filesystem isolation ---
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
# Only these paths are writable
ReadWritePaths=/var/lib/jellyfin /var/log/jellyfin /var/cache/jellyfin /etc/jellyfin
# The library, READ ONLY: Jellyfin has no reason whatsoever to be able
# to delete your films. It is the most important restriction of all.
ReadOnlyPaths=/srv/media

# --- Privileges ---
NoNewPrivileges=true
PrivateDevices=false            # false: it needs /dev/dri for the GPU
DeviceAllow=/dev/dri/renderD128 rw
DeviceAllow=/dev/dri/card0 rw
CapabilityBoundingSet=
AmbientCapabilities=
RestrictSUIDSGID=true

# --- Kernel and memory ---
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectKernelLogs=true
ProtectControlGroups=true
ProtectProc=invisible
MemoryDenyWriteExecute=false    # .NET uses JIT compilation: not possible
LockPersonality=true
RestrictRealtime=true
RestrictNamespaces=true

# --- Network ---
RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6 AF_NETLINK
IPAddressAllow=localhost 192.168.1.0/24 10.8.0.0/24
IPAddressDeny=any

# --- System calls ---
SystemCallFilter=@system-service
SystemCallFilter=~@privileged @resources @obsolete
SystemCallArchitectures=native

# --- Resource limits (cgroups, 07-05) ---
# Stops a runaway transcode from locking up the machine
CPUQuota=350%
MemoryMax=3G
IOWeight=50

$ sudo systemctl daemon-reload && sudo systemctl restart jellyfin
$ systemd-analyze security jellyfin
→ Overall exposure level for jellyfin.service: 2.4 OK

$ sudo -u jellyfin touch /srv/media/test
touch: cannot touch '/srv/media/test': Read-only file system

$ sudo apt install vainfo intel-media-va-driver-non-free

# 1. Does the render device exist?
$ ls -l /dev/dri/
crw-rw---- 1 root video  226,   0 Aug 18 09:02 card0
crw-rw---- 1 root render 226, 128 Aug 18 09:02 renderD128

# 2. What can it do?
$ vainfo --display drm --device /dev/dri/renderD128 2>/dev/null | \
      grep -E 'Driver version|VAProfileH264High|VAProfileHEVCMain|VAProfileAV1'
vainfo: Driver version: Intel iHD driver for Intel(R) Gen Graphics - 24.1.0
      VAProfileH264High               : VAEntrypointVLD        (decodes)
      VAProfileH264High               : VAEntrypointEncSliceLP (encodes)
      VAProfileHEVCMain               : VAEntrypointVLD
      VAProfileHEVCMain10             : VAEntrypointVLD
      VAProfileAV1Profile0            : VAEntrypointVLD

$ sudo usermod -aG render,video jellyfin
$ id jellyfin
uid=996(jellyfin) gid=996(jellyfin) groups=996(jellyfin),44(video),993(render)
$ sudo systemctl restart jellyfin

# With a playback in progress that is transcoding
$ ps -eo pcpu,comm | grep ffmpeg
  6.2 ffmpeg

$ sudo intel_gpu_top -s 1000 | head -8
 Freq MHz    IRQ RC6     Power W        IMC MiB/s
 req  act        %       gpu   pkg     rd     wr
 850  842   1284  12    3.21  8.94   412.1  188.4

 ENGINES     BUSY                     MI_SEM MI_WAIT
 Render/3D   4.12% |█                |      0%      0%
 Video       78.44% |███████████████ |      0%      0%
 VideoEnhance 2.10% |                |      0%      0%

/srv/media/
├── movies/
│   ├── The Third Man (1949)/
│   │   ├── The Third Man (1949) - 1080p.mkv
│   │   ├── The Third Man (1949).en.srt
│   │   └── poster.jpg
│   └── Metropolis (1927)/
│       └── Metropolis (1927) - 1080p.mkv
├── series/
│   └── Series Name (2019)/
│       ├── Season 01/
│       │   ├── Series Name S01E01.mkv
│       │   └── Series Name S01E02.mkv
│       └── Season 02/
│           └── Series Name S02E01.mkv
├── music/
│   └── Artist/
│       └── Album (2004)/
│           ├── 01 - First Track.flac
│           └── 02 - Second Track.flac
└── photos/
    └── 2026/
        └── 2026-07 Pyrenees Holiday/

# See what it would do before doing it (the course's --dry-run convention)
$ for f in /srv/media/incoming/*.mkv; do
      new="$(basename "$f" | sed -E 's/\.(1080p|720p|x264|WEB-DL)//gI; s/\./ /g')"
      printf '%s\n  -> %s\n' "$f" "$new"
  done

$ sudo groupadd -f media
$ sudo usermod -aG media jellyfin
$ sudo usermod -aG media "$USER"
$ sudo chown -R root:media /srv/media
$ sudo find /srv/media -type d -exec chmod 2775 {} +   # SGID: inherits group
$ sudo find /srv/media -type f -exec chmod 0664 {} +

# /etc/samba/smb.conf (after copying the original to .bak-2026-08-18)
[global]
    workgroup = HOME
    server string = Media server
    security = user
    map to guest = never                  # NO guests at all

    # SMB1 is broken by design (WannaCry spread through it).
    # SMB2 as a minimum; SMB3 adds encryption.
    server min protocol = SMB2
    client min protocol = SMB2
    server smb encrypt = desired

    # Listen ONLY on the LAN and the VPN, never on every interface
    interfaces = 127.0.0.1 192.168.1.0/24 10.8.0.0/24
    bind interfaces only = yes
    hosts allow = 127.0.0.1 192.168.1.0/24 10.8.0.0/24
    hosts deny = 0.0.0.0/0

    # No printers: it removes attack surface and log noise
    load printers = no
    printing = bsd
    printcap name = /dev/null
    disable spoolss = yes

    log level = 1
    log file = /var/log/samba/log.%m
    max log size = 1000

[media]
    path = /srv/media
    comment = Family library
    browseable = yes
    read only = yes                       # by default, READ ONLY
    # Only these users can write
    write list = @media
    valid users = @media
    create mask = 0664
    directory mask = 2775
    force group = media
    vfs objects = recycle                 # recycle bin: saves you from deletions
    recycle:repository = .recycle
    recycle:keeptree = yes
    recycle:versions = yes

[photos]
    path = /srv/media/photos
    valid users = @media
    read only = no
    create mask = 0664
    directory mask = 2775
    force group = media

$ sudo apt install samba
$ testparm -s >/dev/null && echo "valid configuration"   # Samba's nginx -t
valid configuration

# Samba users are INDEPENDENT of the system ones, even when the
# name is the same. They have to be created explicitly.
$ sudo smbpasswd -a marta
New SMB password: ********
$ sudo smbpasswd -e marta

$ sudo systemctl restart smbd nmbd
$ smbclient -L //192.168.1.20 -U marta
	Sharename       Type      Comment
	---------       ----      -------
	media           Disk      Family library
	photos          Disk

$ sudo apt install nfs-kernel-server
$ echo '/srv/media 192.168.1.0/24(ro,sync,no_subtree_check,root_squash)' | \
      sudo tee -a /etc/exports
$ sudo exportfs -ra
$ sudo exportfs -v
/srv/media    192.168.1.0/24(ro,sync,no_subtree_check,root_squash)

$ sudo ufw allow from 192.168.1.0/24 to any app Samba
$ sudo ufw allow from 192.168.1.0/24 to any port 8096 proto tcp comment 'Jellyfin'
$ sudo ufw allow from 192.168.1.0/24 to any port 2049 proto tcp comment 'NFS'
$ sudo ufw status | head -6
Status: active
To                         Action      From
--                         ------      ----
Samba                      ALLOW       192.168.1.0/24
8096/tcp (Jellyfin)        ALLOW       192.168.1.0/24
2049/tcp (NFS)             ALLOW       192.168.1.0/24

# /etc/nginx/sites-available/jellyfin — only if you decide to expose it
server {
    listen 443 ssl;
    http2 on;
    server_name media.mydomain.example;

    ssl_certificate     /etc/letsencrypt/live/media.mydomain.example/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/media.mydomain.example/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;

    add_header Strict-Transport-Security "max-age=63072000" always;
    add_header X-Content-Type-Options "nosniff" always;

    # Rate limit against brute force on the login form
    limit_req zone=login burst=5 nodelay;
    client_max_body_size 20M;

    location / {
        proxy_pass http://127.0.0.1:8096;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        # WebSocket: Jellyfin uses it for the playback state
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        # No buffering: this is streaming video
        proxy_buffering off;
    }
}

# ~/media/compose.yml (illustrative fragment)
services:
  sonarr:
    image: lscr.io/linuxserver/sonarr:latest
    environment:
      - PUID=1000
      - PGID=1002          # the media group
      - TZ=Europe/Madrid
    volumes:
      - ./sonarr-config:/config
      - /srv/media/series:/series
    ports:
      - "127.0.0.1:8989:8989"   # localhost ONLY: you reach it over the VPN
    restart: unless-stopped

#!/usr/bin/env bash
#
# home_backup.sh - Backups of the home media server
#
# Strategy:
#   - Irreplaceable (photos, documents) -> restic, off site
#   - Jellyfin configuration            -> restic, daily
#   - Films and music                   -> local Btrfs snapshot
#
set -euo pipefail

readonly SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
source "${SCRIPT_DIR}/lib/common.sh"

readonly HOME_MEDIA="${HOME_MEDIA:-/srv/media}"
readonly HOME_SNAP="${HOME_SNAP:-/srv/media/.snapshots}"
export RESTIC_REPOSITORY="${RESTIC_REPOSITORY:-b2:mydomain-media:/}"

umask 077

local_snapshot() {
    local name="${HOME_SNAP}/$(date +%F)"
    [[ -d "$name" ]] && { log "today's snapshot already exists"; return 0; }
    # Read-only snapshot: it takes no space until something changes
    btrfs subvolume snapshot -r "$HOME_MEDIA" "$name" \
        || die 73 "could not create the snapshot"
    log "snapshot created: $name"

    # Retention: keep 7 daily ones
    local surplus
    mapfile -t surplus < <(find "$HOME_SNAP" -maxdepth 1 -type d -name '20*' \
        | sort -r | tail -n +8)
    local s
    for s in "${surplus[@]:-}"; do
        [[ -n "$s" ]] || continue
        btrfs subvolume delete "$s" && log "old snapshot deleted: $s"
    done
}

offsite_backup() {
    require_command restic
    RESTIC_PASSWORD="$(pass home/restic)" \
    restic backup \
        "${HOME_MEDIA}/photos" \
        "${HOME_MEDIA}/documents" \
        /var/lib/jellyfin \
        /etc/jellyfin \
        --exclude-caches \
        --exclude '*/metadata/*' \
        --tag home \
        || die 74 "restic failed"

    RESTIC_PASSWORD="$(pass home/restic)" \
    restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 12 --prune
}

verify() {
    # An unverified backup is not a backup (05-08)
    RESTIC_PASSWORD="$(pass home/restic)" \
    restic check --read-data-subset=2% || die 74 "the restic verification failed"
    log "verification correct"
}

main() {
    require_command btrfs
    local_snapshot
    offsite_backup
    verify
    log "backup complete"
}

main "$@"

$ sudo btrfs subvolume list /srv/media
ID 258 gen 4412 top level 5 path .snapshots/2026-08-16
ID 259 gen 4488 top level 5 path .snapshots/2026-08-17
ID 260 gen 4501 top level 5 path .snapshots/2026-08-18

# Recovering something deleted by mistake: it is a simple copy
$ sudo cp -a /srv/media/.snapshots/2026-08-17/photos/2026-07 /srv/media/photos/

Annual cost = Average power (W) x 8760 h / 1000 x the price of the kWh

$ sudo apt install powertop lm-sensors
$ sudo sensors-detect --auto >/dev/null

# Calibrate first (it takes a few minutes and measures each state)
$ sudo powertop --calibrate
$ sudo powertop --auto-tune       # applies the recommended settings

$ sudo powertop --time=60 --csv=/tmp/power.csv >/dev/null
$ grep -A6 'Power est' /tmp/power.csv | head -8
The battery reports a discharge rate of 12.4 W
Usage       Events/s   Category       Description
  6.2 ms/s     14.1     Process        ffmpeg
  1.1 ms/s      8.4     Process        jellyfin

# /etc/systemd/system/powertop.service
[Unit]
Description=PowerTOP power-saving settings
After=multi-user.target

[Service]
Type=oneshot
ExecStart=/usr/sbin/powertop --auto-tune
RemainAfterExit=true

[Install]
WantedBy=multi-user.target

$ sudo apt install hdparm

# -B 127: aggressive power management but WITHOUT parking the head every
#         other minute (values < 128 allow spin-down; 254 disables it)
# -S 120: stop after 120 x 5 s = 10 minutes of inactivity
$ sudo hdparm -B 127 -S 120 /dev/sda

# /etc/hdparm.conf — persistent across reboots
/dev/disk/by-id/ata-WDC_WD80EFPX-68C4ZN0_WD-CA0J1234 {
    apm = 127
    spindown_time = 120
}

$ sensors
coretemp-isa-0000
Package id 0:  +42.0°C  (high = +100.0°C, crit = +100.0°C)

$ sudo smartctl -A /dev/sda | grep -i temperature
194 Temperature_Celsius     0x0022   118   105   000    Old_age   Always  -  38

# ~/home-infra/roles/media/defaults/main.yml
---
media_mount_point: /srv/media
media_uuid: 8f3a2c11-4d5e-4a91-b7c2-1e9d0f8a3b45
media_group: media
media_gid: 1002
media_lan_net: 192.168.1.0/24
media_vpn_net: 10.8.0.0/24
media_samba_users: [marta, luis]
media_hw_accel: true
media_gpu_device: /dev/dri/renderD128
media_hdparm_spindown: 120
media_subdirs: [movies, series, music, photos, documents]

# ~/home-infra/roles/media/tasks/main.yml
---
- name: Install the base packages
  ansible.builtin.apt:
    name:
      - btrfs-progs
      - smartmontools
      - samba
      - hdparm
      - powertop
      - restic
    state: present
    update_cache: true
  tags: [packages]

- name: Hardware acceleration packages
  ansible.builtin.apt:
    name: [vainfo, intel-media-va-driver-non-free]
    state: present
  when: media_hw_accel | bool
  tags: [gpu]

- name: Jellyfin repository key in keyrings
  ansible.builtin.get_url:
    url: https://repo.jellyfin.org/jellyfin_team.gpg.key
    dest: /etc/apt/keyrings/jellyfin.asc
    mode: '0644'
  tags: [packages]

- name: Jellyfin repository
  ansible.builtin.deb822_repository:
    name: jellyfin
    types: deb
    uris: https://repo.jellyfin.org/ubuntu
    suites: "{{ ansible_distribution_release }}"
    components: main
    architectures: amd64
    signed_by: /etc/apt/keyrings/jellyfin.asc
  register: jellyfin_repo
  tags: [packages]

- name: Install Jellyfin
  ansible.builtin.apt:
    name: jellyfin
    state: present
    update_cache: "{{ jellyfin_repo.changed }}"
  tags: [packages]

# --- Storage ---
- name: Check that the filesystem exists before mounting it
  ansible.builtin.command: "blkid -U {{ media_uuid }}"
  register: blk
  changed_when: false
  failed_when: blk.rc != 0

- name: Mount the library by UUID with nofail
  ansible.posix.mount:
    path: "{{ media_mount_point }}"
    src: "UUID={{ media_uuid }}"
    fstype: btrfs
    opts: defaults,compress=zstd:3,noatime,nofail,x-systemd.device-timeout=10
    state: mounted

- name: The library group
  ansible.builtin.group:
    name: "{{ media_group }}"
    gid: "{{ media_gid }}"
    state: present

- name: Directory structure with SGID
  ansible.builtin.file:
    path: "{{ media_mount_point }}/{{ item }}"
    state: directory
    owner: root
    group: "{{ media_group }}"
    mode: '2775'
  loop: "{{ media_subdirs }}"

- name: Add jellyfin to the necessary groups
  ansible.builtin.user:
    name: jellyfin
    groups: "{{ [media_group] + (['render', 'video'] if media_hw_accel else []) }}"
    append: true
  notify: Restart jellyfin

- name: Hardening drop-in for jellyfin
  ansible.builtin.template:
    src: jellyfin-override.conf.j2
    dest: /etc/systemd/system/jellyfin.service.d/override.conf
    owner: root
    group: root
    mode: '0644'
  notify:
    - Reload systemd
    - Restart jellyfin

- name: Samba configuration
  ansible.builtin.template:
    src: smb.conf.j2
    dest: /etc/samba/smb.conf
    owner: root
    group: root
    mode: '0644'
    backup: true
    validate: 'testparm -s %s'    # Samba's nginx -t (08-01)
  notify: Restart samba

- name: Firewall - the LAN and the VPN only
  community.general.ufw:
    rule: allow
    src: "{{ item.0 }}"
    port: "{{ item.1 }}"
    proto: tcp
  loop: "{{ [media_lan_net, media_vpn_net] | product(['445', '8096']) | list }}"
  tags: [firewall]

- name: Scrub, SMART and backup timers
  ansible.builtin.copy:
    src: "{{ item }}"
    dest: "/etc/systemd/system/{{ item }}"
    mode: '0644'
  loop:
    - btrfs-scrub.service
    - btrfs-scrub.timer
    - home-backup.service
    - home-backup.timer
  notify: Reload systemd

- name: Enable the timers
  ansible.builtin.systemd:
    name: "{{ item }}"
    enabled: true
    state: started
    daemon_reload: true
  loop: [btrfs-scrub.timer, home-backup.timer, smartd.service]

# --- Verification ---
- name: Verify that hardware acceleration is visible
  ansible.builtin.command: "vainfo --display drm --device {{ media_gpu_device }}"
  register: va
  changed_when: false
  failed_when: "'VAProfileH264High' not in va.stdout"
  when: media_hw_accel | bool
  tags: [verify]

- name: Verify that Jellyfin responds
  ansible.builtin.uri:
    url: "http://127.0.0.1:8096/health"
    status_code: 200
  retries: 5
  delay: 3
  tags: [verify]

# Unattended security updates (06-06)
$ sudo apt install unattended-upgrades
$ sudo dpkg-reconfigure -plow unattended-upgrades

# /etc/apt/apt.conf.d/50unattended-upgrades
Unattended-Upgrade::Automatic-Reboot "true";
Unattended-Upgrade::Automatic-Reboot-Time "05:30";
Unattended-Upgrade::Automatic-Reboot-WithUsers "false";

$ sudo btrfs subvolume snapshot -r /var/lib/jellyfin \
      /srv/media/.snapshots/jellyfin-pre-$(date +%F)

$ sudo systemctl enable --now smartd

# A short test weekly, a long one monthly, and an email alert
$ sudo tee /etc/smartd.conf <<'EOF'
DEVICESCAN -a -o on -S on -n standby,q \
  -s (S/../.././02|L/../(01|15)/./03) \
  -W 4,45,50 \
  -m root -M exec /usr/share/smartmontools/smartd-runner
EOF
$ sudo systemctl restart smartd

$ sudo smartctl -A /dev/sda | \
      awk '$1 ~ /^(5|187|188|197|198)$/ {printf "%-28s %s\n", $2, $10}'
Reallocated_Sector_Ct        0
Reported_Uncorrect           0
Command_Timeout              0
Current_Pending_Sector       0
Offline_Uncorrectable        0

# The symptom: errors in the journal
$ sudo journalctl -k --since today | grep -iE 'ata[0-9]|I/O error|medium error'
kernel: ata2.00: exception Emask 0x0 SAct 0x0 SErr 0x0 action 0x0
kernel: blk_update_request: I/O error, dev sdb, sector 1928374656

$ sudo btrfs device stats /srv/media
[/dev/sda].write_io_errs    0
[/dev/sda].read_io_errs     0
[/dev/sda].corruption_errs  0
[/dev/sdb].write_io_errs    142
[/dev/sdb].read_io_errs     2891
[/dev/sdb].corruption_errs  18

# 1. DO NOT unmount or power off. With RAID 1 the system keeps working.
#    First, check that there is a backup of what is irreplaceable.
$ RESTIC_PASSWORD=$(pass home/restic) restic snapshots --tag home | tail -3

# 2. If the disk STILL responds: hot replacement (the ideal case).
#    Btrfs copies what it can from the old disk and the rest from the mirror.
$ sudo btrfs replace start -f /dev/sdb /dev/sdc /srv/media
$ sudo btrfs replace status /srv/media
0.8% done, 0 write errs, 0 uncorr. read errs

# 3. If the disk NO LONGER responds: mount degraded and add a new one
$ sudo mount -o degraded,compress=zstd:3 UUID=8f3a2c11-... /srv/media
$ sudo btrfs device add /dev/sdc /srv/media
$ sudo btrfs device remove missing /srv/media
$ sudo btrfs balance start -dconvert=raid1 -mconvert=raid1 /srv/media

# 4. Verify that the redundancy has been restored
$ sudo btrfs filesystem df /srv/media
Data, RAID1: total=1.01TiB, used=1.00TiB
Metadata, RAID1: total=8.00GiB, used=6.12GiB

# 5. A full scrub to confirm that everything is intact
$ sudo btrfs scrub start -B /srv/media

# 1. Is it transcoding? The Jellyfin dashboard says so, and so does this:
$ ps -eo pid,pcpu,args | grep '[f]fmpeg' | head -1
  8814 191.2 /usr/lib/jellyfin-ffmpeg/ffmpeg -i /srv/media/movies/...
    -c:v libx264 -preset veryfast -b:v 3000000 ...

# 2. Why is it transcoding? Analyse the file
$ ffprobe -v error -show_entries stream=index,codec_type,codec_name,width,height,channels \
      -of csv=p=0 "/srv/media/movies/Deep Water (2019)/Deep Water (2019).mkv"
0,video,hevc,3840,2160
1,audio,dts,8
2,subtitle,hdmv_pgs_subtitle

# 3. What does the television support? In the Jellyfin log, after playing:
$ sudo journalctl -u jellyfin --since "10 min ago" | grep -i 'transcod\|reason'
[INF] Transcoding reason: VideoCodecNotSupported, AudioCodecNotSupported,
      SubtitleCodecNotSupported

# 4. Is it the network? The living-room Wi-Fi versus a cable
$ iperf3 -c 192.168.1.45 -t 10 -R
[  5]   0.00-10.00  sec  58.2 MBytes  48.8 Mbits/sec

# --- MEASURE 1: enable hardware acceleration (immediate impact) ---
$ vainfo --display drm --device /dev/dri/renderD128 | grep -c EncSlice
6
$ sudo usermod -aG render,video jellyfin
$ sudo systemctl restart jellyfin
# And in the dashboard: Playback > VAAPI, /dev/dri/renderD128,
# ticking HEVC, HEVC 10-bit, VP9 and "HEVC encoding"

# Verify the effect
$ ps -eo pcpu,args | grep '[f]fmpeg' | awk '{print $1}'
5.8
$ sudo intel_gpu_top -s 1000 | grep Video
 Video      74.12% |██████████████   |

# --- MEASURE 2: extract the subtitles to an external file ---
# Graphical PGS subtitles force the VIDEO to be transcoded even when the
# codec is compatible: they have to be "burned" onto the image. The .srt
# ones are sent separately and the client draws them.
$ ffmpeg -i "Deep Water (2019).mkv" -map 0:s:0 -c:s srt "Deep Water (2019).en.srt"

# --- MEASURE 3: convert only the problematic audio, without touching the video ---
# -c:v copy does not re-encode the video: it is seconds, not hours, and
# with no loss of image quality whatsoever.
$ ffmpeg -i input.mkv -c:v copy -c:s copy \
      -c:a ac3 -b:a 640k -ac 6 output.mkv

# --- MEASURE 4: an Ethernet cable or powerline to the living room ---
$ iperf3 -c 192.168.1.45 -t 10 -R
[  5]   0.00-10.00  sec  1.09 GBytes  938 Mbits/sec

TIER 1 - Irreplaceable (402 GB): photos, documents, configuration
  Copy 1: local Btrfs RAID 1 (the original)
  Copy 2: encrypted external USB disk, monthly, in a drawer
  Copy 3: restic in the cloud, daily, encrypted end to end
  -> 3 copies, 2 media, 1 off site. Full 3-2-1.

TIER 2 - Recoverable with effort (800 GB): music
  Copy 1: local Btrfs RAID 1
  Copy 2: the same external USB disk, monthly
  -> No cloud copy: 800 GB a month is not worth 40 h of work.

TIER 3 - Recoverable (4.8 TB): films
  Copy 1: local Btrfs RAID 1
  Copy 2: the original discs on the shelf (you already have it)
  -> No additional copy. RAID covers the failure of one disk and the
     originals cover the rest.

# --- Tier 1: restic in the cloud, daily ---
$ export RESTIC_REPOSITORY="b2:mydomain-media:/"
$ restic init                    # once only

# The passphrase, in pass (06-05). If it is lost, the backup is
# UNREADABLE: there is no possible recovery. It also goes on paper, at a
# relative's house, inside a sealed envelope.
$ pass generate home/restic 40

# --- Tiers 1 and 2: encrypted external USB disk, monthly ---
# LUKS (06-05): if you lose the disk, the data is not readable
$ sudo cryptsetup luksFormat /dev/sdd1
$ sudo cryptsetup open /dev/sdd1 backup-external
$ sudo mkfs.btrfs -L backup /dev/mapper/backup-external

# The monthly copy. --delete is used WITH CARE: if the source is
# unmounted, rsync would delete the whole destination. The prior check
# is not optional.
$ mountpoint -q /srv/media || { echo "source not mounted; aborting"; exit 1; }
$ sudo rsync -aHAX --delete --info=progress2 \
      /srv/media/{photos,documents,music}/ /mnt/backup/
$ sudo umount /mnt/backup && sudo cryptsetup close backup-external

# Automatic, weekly
$ restic check --read-data-subset=5%

# Manual, quarterly: really restore a file and OPEN it
$ restic restore latest --include '/srv/media/photos/2019' --target /tmp/test
$ sha256sum /tmp/test/srv/media/photos/2019/IMG_4412.jpg \
            /srv/media/photos/2019/IMG_4412.jpg
a3f1...  /tmp/test/srv/media/photos/2019/IMG_4412.jpg
a3f1...  /srv/media/photos/2019/IMG_4412.jpg

#!/usr/bin/env bash
#
# home_check.sh - Health check of the home media server
#
# Exit codes:
#   0 = correct   1 = warning   2 = critical
#
# Designed to run from a daily timer, silent when all is well:
# only a state != 0 produces a notification.
#
set -euo pipefail

readonly SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
source "${SCRIPT_DIR}/lib/common.sh"

readonly HOME_MEDIA="${HOME_MEDIA:-/srv/media}"
readonly HOME_DISKS="${HOME_DISKS:-/dev/sda /dev/sdb}"
readonly HOME_SPACE_THRESHOLD="${HOME_SPACE_THRESHOLD:-85}"
readonly HOME_TEMP_THRESHOLD="${HOME_TEMP_THRESHOLD:-45}"
readonly HOME_BACKUP_HOURS="${HOME_BACKUP_HOURS:-36}"
readonly HOME_SCRUB_DAYS="${HOME_SCRUB_DAYS:-45}"

umask 027
overall_status=0

report() {
    local level="$1" message="$2"
    case "$level" in
        ok)       log "OK       $message" ;;
        warn)     error "WARN     $message"; (( overall_status < 1 )) && overall_status=1 ;;
        critical) error "CRITICAL $message"; overall_status=2 ;;
    esac
    return 0
}

check_mount() {
    if ! mountpoint -q "$HOME_MEDIA"; then
        report critical "$HOME_MEDIA is NOT mounted"
        return 0
    fi
    report ok "library mounted"

    # With 'nofail', an absent disk does NOT stop the machine booting: the
    # presence of both devices has to be checked explicitly.
    local n
    n="$(btrfs filesystem show "$HOME_MEDIA" | grep -c '^\s*devid')"
    if (( n < 2 )); then
        report critical "only $n device(s): the RAID 1 is DEGRADED"
    else
        report ok "RAID 1 with $n devices"
    fi
}

check_space() {
    mountpoint -q "$HOME_MEDIA" || return 0
    # 'df' lies with Btrfs in RAID: btrfs's own output is used
    local free_b total_b used_pct
    free_b="$(btrfs filesystem usage -b "$HOME_MEDIA" | \
        awk '/Free \(estimated\)/{gsub(/[^0-9]/,"",$3); print $3}')"
    total_b="$(btrfs filesystem usage -b "$HOME_MEDIA" | \
        awk '/Device size/{gsub(/[^0-9]/,"",$3); print $3/2}')"
    used_pct=$(( 100 - (free_b * 100 / total_b) ))

    if (( used_pct >= 95 )); then
        report critical "library at ${used_pct}% ($(format_bytes "$free_b") free)"
    elif (( used_pct >= HOME_SPACE_THRESHOLD )); then
        report warn "library at ${used_pct}%"
    else
        report ok "space at ${used_pct}% ($(format_bytes "$free_b") free)"
    fi
}

check_btrfs_errors() {
    mountpoint -q "$HOME_MEDIA" || return 0
    local total
    total="$(btrfs device stats "$HOME_MEDIA" | awk '{s+=$2} END {print s+0}')"
    if (( total > 0 )); then
        report critical "btrfs has accumulated $total I/O or corruption errors"
        btrfs device stats "$HOME_MEDIA" | awk '$2>0 {print "         " $0}' >&2
    else
        report ok "no I/O or corruption errors"
    fi
}

check_scrub() {
    mountpoint -q "$HOME_MEDIA" || return 0
    local when days
    when="$(btrfs scrub status "$HOME_MEDIA" | \
        awk -F': ' '/Scrub started/{print $2}')" || true
    if [[ -z "${when:-}" ]]; then
        report warn "there is no record of any scrub having run"
        return 0
    fi
    days=$(( ( $(date +%s) - $(date -d "$when" +%s) ) / 86400 ))
    if (( days > HOME_SCRUB_DAYS )); then
        report warn "last scrub $days days ago"
    else
        report ok "last scrub $days days ago"
    fi
}

check_disks() {
    require_command smartctl
    local d
    for d in $HOME_DISKS; do
        [[ -b "$d" ]] || { report critical "$d does not exist"; continue; }

        # -n standby: do NOT wake a stopped disk just to look at it
        local output
        output="$(smartctl -A -H -n standby "$d" 2>/dev/null)" || true
        if grep -q 'STANDBY' <<<"$output"; then
            report ok "$d in standby (not woken up)"
            continue
        fi

        # The attributes that predict failures, not the overall verdict
        local realloc pending unreadable temp
        realloc="$(awk '$1==5   {print $10+0}' <<<"$output")"
        pending="$(awk '$1==197 {print $10+0}' <<<"$output")"
        unreadable="$(awk '$1==198 {print $10+0}' <<<"$output")"
        temp="$(awk '$1==194 {print $10+0}' <<<"$output")"

        if (( ${unreadable:-0} > 0 || ${pending:-0} > 0 )); then
            report critical "$d: $pending pending, $unreadable unreadable: REPLACE IT"
        elif (( ${realloc:-0} > 0 )); then
            report warn "$d: $realloc reallocated sectors: watch it"
        else
            report ok "$d with no bad sectors"
        fi

        if (( ${temp:-0} >= 50 )); then
            report critical "$d at ${temp}C"
        elif (( ${temp:-0} >= HOME_TEMP_THRESHOLD )); then
            report warn "$d at ${temp}C (ideal < 45)"
        fi
    done
}

check_services() {
    local s
    for s in jellyfin smbd smartd; do
        systemctl is-active --quiet "$s" \
            && report ok "$s active" \
            || report critical "$s is NOT active"
    done

    # That it responds, not just that the process exists
    if curl -sf -m 5 -o /dev/null http://127.0.0.1:8096/health; then
        report ok "jellyfin responds"
    else
        report critical "jellyfin does not respond on 8096"
    fi
}

check_backups() {
    local marker=/var/lib/home-backup/last-successful
    if [[ ! -f "$marker" ]]; then
        report critical "there is no record of any successful backup"
        return 0
    fi
    local hours
    hours=$(( ( $(date +%s) - $(stat -c %Y "$marker") ) / 3600 ))
    if (( hours > HOME_BACKUP_HOURS * 2 )); then
        report critical "last successful backup ${hours} h ago"
    elif (( hours > HOME_BACKUP_HOURS )); then
        report warn "last successful backup ${hours} h ago"
    else
        report ok "last successful backup ${hours} h ago"
    fi
}

check_acceleration() {
    [[ -e /dev/dri/renderD128 ]] || { report warn "no GPU reachable"; return 0; }
    if vainfo --display drm --device /dev/dri/renderD128 2>/dev/null | \
            grep -q VAEntrypointEncSlice; then
        report ok "hardware acceleration available"
    else
        report warn "the GPU does not expose hardware encoding"
    fi
}

main() {
    require_command btrfs
    require_command curl

    check_mount
    check_space
    check_btrfs_errors
    check_scrub
    check_disks
    check_services
    check_backups
    check_acceleration

    case "$overall_status" in
        0) log "home media server correct" ;;
        1) error "check completed with WARNINGS" ;;
        2) error "check completed in a CRITICAL state" ;;
    esac
    return "$overall_status"
}

main "$@"

$ shellcheck ~/scripts/home_check.sh && echo "no warnings"
no warnings

$ ~/scripts/home_check.sh; echo "status: $?"
[2026-08-18 08:00:03] OK       library mounted
[2026-08-18 08:00:03] OK       RAID 1 with 2 devices
[2026-08-18 08:00:03] OK       space at 28% (6.3 TiB free)
[2026-08-18 08:00:04] OK       no I/O or corruption errors
[2026-08-18 08:00:04] OK       last scrub 12 days ago
[2026-08-18 08:00:04] OK       /dev/sda in standby (not woken up)
[2026-08-18 08:00:04] OK       /dev/sdb in standby (not woken up)
[2026-08-18 08:00:05] OK       jellyfin active
[2026-08-18 08:00:05] OK       smbd active
[2026-08-18 08:00:05] OK       smartd active
[2026-08-18 08:00:05] OK       jellyfin responds
[2026-08-18 08:00:05] OK       last successful backup 6 h ago
[2026-08-18 08:00:06] OK       hardware acceleration available
[2026-08-18 08:00:06] home media server correct
status: 0

# /etc/systemd/system/home-check.timer
[Unit]
Description=Daily check of the home media server

[Timer]
OnCalendar=*-*-* 08:00:00
Persistent=true

[Install]
WantedBy=timers.target

# /etc/systemd/system/home-check.service
[Unit]
Description=Health check of the home media server
# Notify ONLY on failure: silence when all is well
OnFailure=notify-home@%n.service

[Service]
Type=oneshot
User=operator
ExecStart=/home/operator/scripts/home_check.sh