diff --git a/docs/Dankserver/Entropy Volume.md b/docs/Dankserver/Entropy Volume.md new file mode 100644 index 0000000..a4b6c97 --- /dev/null +++ b/docs/Dankserver/Entropy Volume.md @@ -0,0 +1,43 @@ +# Entropy Volume + +The Dankserver entropy volume is a RAID-backed LUKS filesystem mounted at +`/mnt/entropy`. The command-line helper reuses the host's desktop-integrated +`udisks2`, `crypttab`, and `fstab` configuration; it does not store or handle +the passphrase itself. + +## Command-line mount + +```bash +/home/dank/serverAppConfigs/scripts/mount-entropy.sh +``` + +Run it as the normal desktop user (`dank`), not from a root shell. `udisksctl` +will securely prompt for the LUKS passphrase. `sudo mount /mnt/entropy` then +uses the existing `/etc/fstab` entry, preserving its options: + +```text +nosuid,nodev +``` + +The existing mountpoint is owned by `dank:dankserver` with mode `0755`; the +helper deliberately does not run `chmod` or `chown`, so it cannot silently +change those permissions. + +## Device path + +The current storage chain is: + +```text +/dev/md0 -> LUKS UUID cd86c728-459e-4f3a-bcc2-41ecf84685ec + -> ext4 label entropy + -> /mnt/entropy +``` + +The helper checks that `/dev/md0` exists and exits successfully if the volume +is already mounted. It is intentionally specific to this host and volume: +that avoids accidentally unlocking or mounting a different disk. + +## Related + +- [[Storage Policy]] +- [[Dankserver Stack]] diff --git a/docs/index.md b/docs/index.md index ae451c4..7a96627 100644 --- a/docs/index.md +++ b/docs/index.md @@ -30,6 +30,10 @@ covers both workloads). - [[Deployment Flow]] — git-based deploy, target map, health checks - [[Testing Policy]] — the test seams and how to run them +## Dankserver Storage + +- [[Entropy Volume]] — command-line unlock and mount helper + ## Dankserver Services - [[RomM]] — retro game manager diff --git a/scripts/mount-entropy.sh b/scripts/mount-entropy.sh new file mode 100755 index 0000000..557612d --- /dev/null +++ b/scripts/mount-entropy.sh @@ -0,0 +1,32 @@ +#!/usr/bin/env bash +# Unlock and mount Dankserver's encrypted entropy volume. +# +# The desktop flow uses the system's crypttab and fstab entries. Reuse those +# entries here instead of embedding a passphrase, mount options, or ownership +# changes in this helper. udisksctl reads the passphrase through its secure +# desktop/terminal authentication path. +set -euo pipefail + +MOUNTPOINT='/mnt/entropy' +MAPPER='/dev/mapper/luks-cd86c728-459e-4f3a-bcc2-41ecf84685ec' + +if mountpoint -q "$MOUNTPOINT"; then + printf '%s is already mounted.\n' "$MOUNTPOINT" + exit 0 +fi + +if [ ! -e /dev/md0 ]; then + printf 'ERROR: RAID device /dev/md0 is not available.\n' >&2 + exit 1 +fi + +if [ ! -e "$MAPPER" ]; then + udisksctl unlock --block-device /dev/md0 +fi + +# udisks2 may mount automatically as part of unlocking. Do not attempt a +# second mount in that case. +if ! mountpoint -q "$MOUNTPOINT"; then + sudo mount "$MOUNTPOINT" +fi +printf 'Mounted %s.\n' "$MOUNTPOINT" diff --git a/tests/mount_entropy.bats b/tests/mount_entropy.bats new file mode 100644 index 0000000..30e4b66 --- /dev/null +++ b/tests/mount_entropy.bats @@ -0,0 +1,25 @@ +#!/usr/bin/env bats +# Seam: the entropy helper unlocks the known LUKS-on-md device and mounts via +# the host's fstab entry, preserving the existing mount options and directory +# ownership rather than inventing a second mount configuration. + +load helpers + +@test "entropy helper is executable and has the expected safe shell shape" { + run bash -c "test -x '$REPO_ROOT/scripts/mount-entropy.sh'" + [ "$status" -eq 0 ] + + run grep -E '^set -euo pipefail$' "$REPO_ROOT/scripts/mount-entropy.sh" + [ "$status" -eq 0 ] + + run grep -F 'udisksctl unlock --block-device /dev/md0' "$REPO_ROOT/scripts/mount-entropy.sh" + [ "$status" -eq 0 ] + + run grep -F 'sudo mount "$MOUNTPOINT"' "$REPO_ROOT/scripts/mount-entropy.sh" + [ "$status" -eq 0 ] +} + +@test "entropy helper does not embed a secret or alter mount ownership" { + run grep -Eiq 'password|secret|chmod|chown' "$REPO_ROOT/scripts/mount-entropy.sh" + [ "$status" -eq 1 ] +}