From 8326126a6d5c3b22b3660cd864b6fcdb56e544dd Mon Sep 17 00:00:00 2001 From: Administrator Date: Sun, 22 Feb 2026 04:17:35 +0000 Subject: [PATCH] docs: update Netgrimoire/Pocket/Deployment_Guide --- Netgrimoire/Pocket/Deployment_Guide.md | 227 ++++++++++++++++++++----- 1 file changed, 180 insertions(+), 47 deletions(-) diff --git a/Netgrimoire/Pocket/Deployment_Guide.md b/Netgrimoire/Pocket/Deployment_Guide.md index 96f0071..df52920 100644 --- a/Netgrimoire/Pocket/Deployment_Guide.md +++ b/Netgrimoire/Pocket/Deployment_Guide.md @@ -2,7 +2,7 @@ title: Pocket Grimoire description: published: true -date: 2026-02-22T03:55:29.977Z +date: 2026-02-22T04:17:23.914Z tags: editor: markdown dateCreated: 2026-02-20T04:41:35.122Z @@ -50,12 +50,12 @@ Pocket Grimoire is a portable companion to the Netgrimoire homelab, providing of - Photos and documents - System backups and configs - SSH keys - - VeraCrypt containers (optional) - - **Does NOT contain media or Stash data** + - **Does NOT contain media, Stash data, or VeraCrypt containers** - **SSD #2 – GREEN** (2TB+, encrypted, for personal trips) - Personal media library (H.264/AAC movies and TV) - Stash-Pocket data (database, previews, blobs) + - VeraCrypt containers (for ultra-sensitive files) - Personal content organized under `/Green/` structure - Connected during personal/solo trips - Syncs from `/export/vault/Green/` on Netgrimoire @@ -282,19 +282,19 @@ Headroom: 78W │ ├── wiki/ # Wiki.js backups │ ├── photos/ # Photo backups │ └── documents/ # Document backups -├── repos/ # Git repository mirrors -└── veracrypt-containers/ # VeraCrypt containers (optional) - └── vault.vc +└── repos/ # Git repository mirrors /srv/greenpg/ # GREEN SSD (personal, rotated) └── Pocket/ # Dataset received from vault/Green/Pocket ├── media/library/ # Personal media files │ ├── movies/ │ └── tv/ - └── stash/ # Stash-Pocket data - ├── config/ # Stash database - ├── generated/ # Previews - └── blobs/ # Scene markers + ├── stash/ # Stash-Pocket data + │ ├── config/ # Stash database + │ ├── generated/ # Previews + │ └── blobs/ # Scene markers + └── veracrypt/ # VeraCrypt containers + └── sensitive.vc # Encrypted container files /srv/mediapg/ # MEDIA-FAMILY SSD (family, rotated) └── library/ # Family media files @@ -357,22 +357,22 @@ sudo raspi-config ### 2. Install VeraCrypt (Optional - For Encrypted Container Files) **VeraCrypt** allows you to mount encrypted container files as virtual drives. This is useful for: -- Encrypted file containers synced from Netgrimoire +- Encrypted file containers for ultra-sensitive data - Portable encrypted volumes that can be moved between systems -- Additional layer of encryption beyond ZFS +- Additional layer of encryption beyond ZFS (nested encryption) +- Cross-platform compatibility (Windows, Mac, Linux) **Installation:** ```bash -# Install dependencies -sudo apt install -y wget libfuse2 +# Add VeraCrypt PPA repository +sudo add-apt-repository ppa:unit193/encryption -y -# Download VeraCrypt (check for latest version at veracrypt.fr) -wget https://launchpad.net/veracrypt/trunk/1.25.9/+download/veracrypt-1.25.9-Debian-12-arm64.deb +# Update package lists +sudo apt update # Install VeraCrypt -sudo dpkg -i veracrypt-*.deb -sudo apt-get install -f # Fix any dependency issues +sudo apt install veracrypt -y # Verify installation veracrypt --text --version @@ -441,9 +441,9 @@ sudo nano /usr/local/sbin/mount-veracrypt-vault.sh ```bash #!/bin/bash -# Mount VeraCrypt container with password prompt +# Mount VeraCrypt container from GREEN drive -CONTAINER="/srv/vaultpg/containers/vault.vc" +CONTAINER="/srv/greenpg/Pocket/veracrypt/sensitive.vc" MOUNT_POINT="/mnt/veracrypt/vault1" if mount | grep -q "$MOUNT_POINT"; then @@ -451,7 +451,14 @@ if mount | grep -q "$MOUNT_POINT"; then exit 0 fi -echo "Mounting VeraCrypt container..." +# Check if GREEN drive is mounted +if [ ! -f "$CONTAINER" ]; then + echo "Error: VeraCrypt container not found at $CONTAINER" + echo "Is GREEN drive mounted?" + exit 1 +fi + +echo "Mounting VeraCrypt container from GREEN drive..." sudo veracrypt --text --mount "$CONTAINER" "$MOUNT_POINT" if [ $? -eq 0 ]; then @@ -482,8 +489,11 @@ veracrypt --text --list **VeraCrypt Container Creation (Do this on Netgrimoire first):** ```bash +# Create directory in your existing vault/Green/Pocket dataset +sudo mkdir -p /export/Green/Pocket/veracrypt + # Create a new VeraCrypt container (example: 10GB) -veracrypt --text --create /path/to/container.vc +veracrypt --text --create /export/Green/Pocket/veracrypt/sensitive.vc # Follow prompts: # - Volume type: Normal @@ -498,13 +508,19 @@ veracrypt --text --create /path/to/container.vc **Sync VeraCrypt Container via ZFS:** ```bash -# Store container file in ZFS dataset -sudo zfs create vaultpg/veracrypt-containers +# VeraCrypt containers are stored in vault/Green/Pocket/veracrypt/ +# They automatically sync to GREEN drive with the rest of the Pocket dataset -# Container location: /srv/vaultpg/veracrypt-containers/vault.vc +# On Netgrimoire: +# /export/Green/Pocket/veracrypt/sensitive.vc -# This file syncs from Netgrimoire like any other file -# Then mount it after sync completes +# After sync to GREEN drive: +# /mnt/pocket-green/Pocket/veracrypt/sensitive.vc + +# On Pocket Grimoire after import: +# /srv/greenpg/Pocket/veracrypt/sensitive.vc + +# The container syncs automatically when you sync the Green/Pocket dataset ``` **When to Use VeraCrypt vs ZFS Encryption:** @@ -522,9 +538,11 @@ sudo zfs create vaultpg/veracrypt-containers - Don't need to move encrypted data to non-Linux systems **For Pocket Grimoire, recommended approach:** -- ZFS encryption for main vault and media SSDs (always) -- VeraCrypt for specific sensitive containers (optional) -- Example: Tax documents, personal files in VeraCrypt container on ZFS-encrypted drive +- ZFS encryption for VAULT and GREEN SSDs (always) +- VeraCrypt for ultra-sensitive files on GREEN drive (optional) +- Example: Tax documents, financial records, personal files +- VeraCrypt containers stored in `/export/Green/Pocket/veracrypt/` +- Syncs to GREEN drive automatically with other Pocket data ### 3. Install ZFS @@ -551,11 +569,11 @@ This approach allows you to: **Drive #1: VAULT** (1-2TB, encrypted, always connected) - Purpose: Backups and system data ONLY - Contains: Git repos, Wiki backups, Kopia repository, photos, documents -- Does NOT contain media or Stash data +- Does NOT contain media, Stash data, or VeraCrypt containers **Drive #2: GREEN** (2TB+, encrypted, rotated for personal trips) -- Purpose: Personal media and Stash-Pocket data -- Contains: Personal media library, Stash database/previews/blobs +- Purpose: Personal media, Stash-Pocket data, and VeraCrypt containers +- Contains: Personal media library, Stash database/previews/blobs, VeraCrypt files - Syncs from `/export/vault/Green/` on Netgrimoire **Drive #3: MEDIA-FAMILY** (2TB+, unencrypted, rotated for family trips) @@ -601,7 +619,6 @@ sudo zfs create pocket-vault/backups # General backups sudo zfs create pocket-vault/backups/wiki # Wiki.js backups sudo zfs create pocket-vault/backups/photos # Photo backups sudo zfs create pocket-vault/backups/documents # Document backups -sudo zfs create pocket-vault/veracrypt-containers # VeraCrypt (optional) # Set ownership sudo chown -R 1000:1000 /mnt/pocket-vault @@ -724,6 +741,11 @@ ls -lh /mnt/pocket-green/Pocket/ du -sh /mnt/pocket-green/Pocket/ ``` +**Important Note on Pool Naming:** +- On Netgrimoire during initial build: Pool is called `pocket-green` +- After moving to Pocket Grimoire: Pool is renamed to `greenpg` during import +- If you've already moved the drive to Pocket and back, use: `sudo syncoid vault/Green/Pocket greenpg/Pocket` + **Option B: Manual ZFS Send (Advanced)** ```bash @@ -743,21 +765,25 @@ sudo zfs snapshot vault/Green/Pocket@initial sudo zfs send vault/Green/Pocket@initial | \ sudo zfs receive pocket-green/Pocket -# This creates: pocket-green/Pocket (matching the structure) +# Or if pool was already renamed to greenpg: +# sudo zfs send vault/Green/Pocket@initial | \ +# sudo zfs receive greenpg/Pocket + +# This creates: pocket-green/Pocket (or greenpg/Pocket) # NOT just "pocket-green" (which is the pool name) # Verify received -zfs list pocket-green/Pocket -ls -lh /mnt/pocket-green/Pocket/ +zfs list pocket-green/Pocket # or greenpg/Pocket +ls -lh /mnt/pocket-green/Pocket/ # or /srv/greenpg/Pocket # Verify data integrity -du -sh /mnt/pocket-green/Pocket/ +du -sh /mnt/pocket-green/Pocket/ # or /srv/greenpg/Pocket ``` **Both options create the same result:** ``` # The data structure will be: -# /mnt/pocket-green/Pocket/ +# /mnt/pocket-green/Pocket/ (or /srv/greenpg/Pocket if already renamed) # ├── media/library/ # │ ├── movies/ # │ └── tv/ @@ -770,9 +796,9 @@ du -sh /mnt/pocket-green/Pocket/ **Important notes:** - The `vault/Green/Pocket` dataset is encrypted on Netgrimoire - `zfs send` transfers the data (decrypted during send) -- `pocket-green` pool has its own encryption (encrypts during receive) +- `pocket-green` (or `greenpg`) pool has its own encryption (encrypts during receive) - Result: Data is encrypted at rest on both systems with different keys -- The dataset name becomes `pocket-green/Pocket` (not `pocket-green/Green/Pocket`) +- The dataset name becomes `pocket-green/Pocket` initially, or `greenpg/Pocket` if pool was already renamed - **Recommended:** Use syncoid (Option A) - it's simpler and handles everything automatically @@ -801,12 +827,22 @@ du -sh /mnt/pocket-media/library/ # CRITICAL: Export pools before physically disconnecting drives sudo zpool export pocket-vault + +# For GREEN drive - check which name it has +zpool list | grep -E "pocket-green|greenpg" + +# If it shows "pocket-green": sudo zpool export pocket-green -sudo zpool export pocket-media # if created + +# If it shows "greenpg" (already renamed from previous import): +sudo zpool export greenpg + +# For MEDIA-FAMILY (if created): +sudo zpool export pocket-media # or mediapg if renamed # Verify exported zpool list -# Should NOT show pocket-* pools +# Should NOT show pocket-* or *pg pools ``` **Physically disconnect drives from Netgrimoire.** @@ -2013,7 +2049,72 @@ docker ps **If anything fails during this test, debug at home before traveling!** -### 10. Configure Ongoing ZFS Sync (After Initial Setup) +### 10. Resync GREEN Drive When Connected to Netgrimoire + +**If you've physically moved the GREEN drive back to Netgrimoire for fast resyncing:** + +```bash +# On Netgrimoire with GREEN SSD connected + +# 1. Check which name the pool has +zpool list | grep -E "pocket-green|greenpg" + +# 2. Import if not already imported +# If pool is named "pocket-green": +sudo zpool import pocket-green + +# If pool is named "greenpg" (already renamed from Pocket): +sudo zpool import greenpg + +# 3. Load encryption key +sudo zfs load-key pocket-green # or greenpg +# Enter GREEN drive passphrase + +# 4. Mount datasets +sudo zfs mount -a + +# 5. Verify mounted +zfs list | grep -E "pocket-green|greenpg" +# Should show the Pocket dataset mounted + +# 6. Resync using syncoid +# If pool is named "pocket-green": +sudo syncoid vault/Green/Pocket pocket-green/Pocket + +# If pool is named "greenpg": +sudo syncoid vault/Green/Pocket greenpg/Pocket + +# Syncoid shows progress: +# Sending incremental vault/Green/Pocket@... +# 2.3GB 0:01:23 [28.4MB/s] [===============>] 100% + +# 7. Verify sync completed +zfs list pocket-green/Pocket # or greenpg/Pocket +du -sh /mnt/pocket-green/Pocket/ # or /srv/greenpg/Pocket + +# 8. Export pool before disconnecting +sudo zfs unmount -a +sudo zpool export pocket-green # or greenpg + +# 9. Safe to physically disconnect GREEN SSD +``` + +**Quick Commands Based on Pool Name:** + +```bash +# Check pool name first +POOL_NAME=$(zpool list | grep -oE "pocket-green|greenpg") +echo "Pool name: $POOL_NAME" + +# Then use appropriate commands +sudo zpool import $POOL_NAME +sudo zfs load-key $POOL_NAME +sudo zfs mount -a +sudo syncoid vault/Green/Pocket ${POOL_NAME}/Pocket +sudo zpool export $POOL_NAME +``` + +### 11. Configure Ongoing ZFS Sync (After Initial Setup) **Once drives are on Pocket Grimoire, set up ongoing sync from Netgrimoire:** @@ -2067,7 +2168,7 @@ zfs list greenpg/Pocket du -sh /srv/greenpg/Pocket/ ``` -### 11. Verify Data Synced from Netgrimoire +### 12. Verify Data Synced from Netgrimoire ```bash # Check VAULT data present (backups only) ls /srv/vaultpg/kopia/ @@ -2257,16 +2358,47 @@ sudo zpool import -a # Load encryption keys sudo zfs load-key vaultpg -sudo zfs load-key mediapg +sudo zfs load-key greenpg # GREEN drive # Mount all sudo zfs mount -a # If corruption detected sudo zpool scrub vaultpg -sudo zpool scrub mediapg +sudo zpool scrub greenpg ``` +### Pool Name Confusion (pocket-green vs greenpg) + +**Problem:** You're not sure if your GREEN pool is named `pocket-green` or `greenpg` + +**Solution:** +```bash +# Check which name the pool has +zpool list | grep -E "pocket-green|greenpg" + +# If on Netgrimoire (initial build): Usually "pocket-green" +# If on Pocket Grimoire: Always "greenpg" (renamed during import) +# If moved back to Netgrimoire: Keeps "greenpg" name from Pocket + +# Import using the correct name +sudo zpool import pocket-green # if shows pocket-green +# OR +sudo zpool import greenpg # if shows greenpg + +# For syncoid, use whichever name it has: +sudo syncoid vault/Green/Pocket pocket-green/Pocket # if pocket-green +# OR +sudo syncoid vault/Green/Pocket greenpg/Pocket # if greenpg +``` + +**Why the name changes:** +- Created on Netgrimoire: `pocket-green` (temporary name for building) +- Imported to Pocket: Renamed to `greenpg` (permanent name for travel) +- Moved back to Netgrimoire: Keeps `greenpg` name (doesn't revert) + +**Best practice:** After first import to Pocket, the pool is permanently `greenpg` + ### Docker Containers Not Starting ```bash # Check if ZFS pools are mounted first @@ -2938,3 +3070,4 @@ For issues or improvements to this documentation: --- *This guide was created for Pocket Grimoire deployment and maintenance. Keep this documentation updated as the system evolves.* +