TrueNAS API Migration Project Plan#

TrueNAS is warning that one or more tools connected to it are still using an older communication method that will stop working in a future TrueNAS upgrade. The solution is to identify every tool using that method—including the AI agent, Home Assistant, Homepage, and any other integrations—move each one to the supported communication method, and test them one at a time before upgrading the servers. This project changes how the tools talk to TrueNAS; it does not change storage, datasets, backups, or other data. The AI agent is a likely source of the warning, but it must be confirmed rather than assumed to be the only source.

Paperless-ngx Document Management and Backup#

This note documents the Paperless-ngx deployment on HP1Docker (10.1.2.202), its document locations, and the file-level backup path to HP1TrueNAS (10.1.2.201). It reflects the live configuration inspected on 2026-09-14.

1. Service architecture#

Paperless-ngx runs from /home/marc/docker-compose/paperless on HP1Docker using Docker Compose:

The Compose definition is stored at:

UniFi UNAS-Pro Master Backup Strategy: Native Rsync Daemon (Pull) Architecture#

This document defines the complete operational standard, architecture, schedule matrix, node-by-node configuration reference, and disaster recovery procedures for backing up all shared data from the master UniFi UNAS-Pro NAS (10.1.2.2) across the fleet of 5 TrueNAS SCALE storage nodes (HP1, HP2, HP3, HP6, HP7). It is designed to be sufficient to fully reconstruct the entire setup from scratch.

The former HP7TrueNAS node (10.1.1.17) is now HP6TrueNAS. The storage dataset, SMB shares, and backup script have been renamed to the HP6 identifiers.

Scripts Management Migration Plan#

This document is the master architectural migration plan for establishing /Users/marc/Scripts as your primary local master Git repository, linked to git@github.com:marcoue/Scripts.git, with automated mirroring to the UNAS-Pro NAS (/Volumes/Software/Software/Scripts/) and automated pull execution by remote TrueNAS/Linux/Proxmox nodes.

1. Executive Summary & Architecture Goal#

🎯 Primary Master Architecture#

1. Master Repository: /Users/marc/Scripts on your Mac SSD is your primary master repository for editing, testing, running, and managing all homelab scripts.
2. GitHub Remote: Linked to git@github.com:marcoue/Scripts.git on branch main.
3. Automated NAS Mirroring: A Git post-commit hook automatically syncs committed scripts from ~/Scripts/ to /Volumes/Software/Software/Scripts/ on UNAS-Pro.
4. Remote Server Pull Execution: Remote servers (HP1, HP2, HP3, HP7, HP8, Proxmox, Linux) pull their scripts from UNAS-Pro (Software/Scripts/) on their scheduled runs.

🔄 Data & Deployment Flow#

  [Mac Workstation] (Primary Master Workspace)
   └── ~/Scripts/ (git@github.com:marcoue/Scripts.git)
        ├── MacOS/
        ├── Linux/
        ├── Proxmox/
        └── TrueNAS/
             │
             ├── (git commit)
             ▼
        [Git post-commit Hook]
             │
             ├── (rsync auto-mirror)
             ▼
  [UNAS-Pro Master NAS] (Distribution Mirror)
   └── /Volumes/Software/Software/Scripts/
        ├── MacOS/
        ├── Linux/
        ├── Proxmox/
        └── TrueNAS/ (Exposed as Rsync Module: root@10.1.2.2::Software/Scripts/TrueNAS/)
             │
             ├── (Rsync pull on schedule)
             ▼
  [Remote Nodes: HP1, HP2, HP3, HP7, HP8, Proxmox, Linux]
   └── Local Execution of Version-Controlled Scripts

📂 1.1 Filesystem Standard & Disaster Recovery Protocol#

1. Standard POSIX Filesystem Path:
   • The destination path /Volumes/Software/Software/Scripts/ (and subfolders MacOS/, Linux/, Proxmox/, TrueNAS/) is a standard, plain-text directory tree residing on the mounted Software SMB share (smb://10.1.2.2/Software). There are zero proprietary databases, hidden hooks, or custom file structures on the NAS.
2. Mac Auto-Mount Convenience (Login Items):
   • To ensure the SMB share is always available for Git post-commit auto-mirroring, add /Volumes/Software to macOS System Settings > General > Login Items.
3. macOS Reinstall / Disaster Recovery:
   • Reinstalling or replacing macOS on your Mac Studio has zero effect on UNAS-Pro or TrueNAS servers. The NAS files remain intact, and TrueNAS backup cron jobs continue executing without interruption.
   • To restore your Mac workstation repo after a fresh macOS install:

     # Step 1: Clone master repository from GitHub
     git clone git@github.com:marcoue/Scripts.git ~/Scripts
     
     # Step 2: Re-install 1-line Git post-commit auto-mirror hook
     cat << 'EOF' > ~/Scripts/.git/hooks/post-commit
     #!/usr/bin/env bash
     if [ -d "/Volumes/Software/Software/Scripts" ]; then
         rsync -av --delete --exclude='.git' --exclude='*.log' /Users/marc/Scripts/ /Volumes/Software/Software/Scripts/
     fi
     EOF
     chmod +x ~/Scripts/.git/hooks/post-commit

2. Complete Script Inventory & Mapping#

The following table lists all existing scripts found across your NAS repository (git@github.com:marcoue/Scripts.git) and local Mac folder (~/Scripts/), mapped to their final category subfolders:

UNAS-Pro Backup Migration Plan: SMB (Push) to Native Rsync Daemon (Pull)#

Antigravity Chat: agy –conversation=4c0c9b6d-2722-4fd6-a4aa-638c75ab46f4

This document is the complete master migration plan for transitioning the UNAS-Pro backup strategy from the UniFi Drive UI-managed SMB (Push) setup to a Native Rsync Daemon (Pull) model.

Because the UniFi Drive UI natively supports Rsync server settings and shared folder modules, migrating to Rsync requires configuring your TrueNAS SCALE servers (HP1, HP2, HP3, HP6, HP7) to pull the backups directly from the UNAS-Pro Rsync daemon over TCP port 873.

Lab-Servers Infrastructure & Virtualization Security Analysis#

VERDICT: [VERIFIED] SECURE AND HARDENED SECURITY SCORE: 97 / 100 (Grade: A+) An empirical security audit of the Lab-Servers network (10.1.1.0/24, interface br11) confirms that all Proxmox VE hypervisor nodes, Proxmox Datacenter Manager (PDM), Proxmox Backup Servers (PBS), TrueNAS storage arrays, and virtual server infrastructure operate on a dedicated 10G SFP+ aggregated network protected by Linux kernel firewall rules (iptables), gateway management isolation, active honeypot monitoring (10.1.1.254), and strict inter-VLAN boundary drops.

Proxmox Disk Passthrough Guide#

The HP7TrueNAS passthrough entry below is VM 207 and remains validation-pending. The former HP6Proxmox host was decommissioned; 10.1.1.16 is now assigned to HP6TrueNAS, formerly HP7TrueNAS. Do not apply the VM 207 commands without revalidating the deployment. HP7BackupServer is a separate VM 217, now at 10.1.1.217.

1. Discovery Commands#

Use these commands to identify physical disks on the Proxmox host.

# Install hardware lister
apt install lshw

# List disks and storage controllers
lshw -class disk -class storage

# List all Physical Disk IDs (The ID needed for passthrough)
ls -l /dev/disk/by-id/

# Advanced list: Maps Device to ID and filters out partitions/LVM
lsblk |awk 'NR==1{print $0" DEVICE-ID(S)"}NR>1{dev=$1;printf $0" ";system("find /dev/disk/by-id -lname \"*"dev"\" -printf \" %p\"");print "";}'|grep -v -E 'part|lvm'

2. Configuration Requirements#

Adding Serials (Crucial for TrueNAS/ZFS)#

In TrueNAS manually edit the VM config file to ensure disk serials persist:

Syncthing Installation & Configuration Guide#

1. #truenas TrueNAS Scale Installation#

Increase Inotify Limit#

For real-time file watching on large datasets, increase the inotify limit in the TrueNAS backend.

1. Go to System Settings > Advanced > Sysctl.
2. Add New Sysctl:
   • Variable: fs.inotify.max_user_watches
   • Value: 524288
   • Description: Increase inotify limit for Syncthing.
3. Verify persistence via Shell:

cat /proc/sys/fs/inotify/max_user_watches

App Deployment#

1. Apps > Settings > Advanced: Disable “Host Path Safety Check” (if using existing datasets).
2. Catalog: Search for and install the Syncthing Enterprise version.
3. Storage Configuration:
   • Type: Host Path
   • Host Path: /mnt/HP1-4TBSSD-Raid0/HP1Storage (or your specific data path).
   • Mount Path: HP1Storage
4. Access: Open the Web UI at http://[IP]:31000. Set an Admin password immediately.

2. Synology DSM Installation (via Docker)#

Increase Inotify Limit#

1. Connect via SSH and run:

echo "fs.inotify.max_user_watches=204800" | sudo tee -a /etc/sysctl.d/90-override.conf
echo 204800 | sudo tee /proc/sys/fs/inotify/max_user_watches

Identify User IDs (PUID/PGID)#

To avoid permission issues, run the container as your specific user.

TrueNAS Administration Guide#

The complete UNAS-Pro backup architecture, schedules, TrueNAS node configuration, and recovery procedures are documented in Unifi UNAS-Pro Backup Strategy.

1. TrueNAS Scale: Initial Setup & Security#

Virtual Machine Configuration (Proxmox)#

• Initial Setup: Create the VM. Add a second virtual disk (10GB) for apps and home directories.
• Post-Login: Verify the Time Zone is accurate.
• Duplicate Serial Error: If Proxmox reports Disks have duplicate serial numbers, add serials manually in the PVE host:

  nano /etc/pve/qemu-server/212.conf
  # Add serial strings:
  scsi0: Storage:vm-212-disk-0,discard=on,size=32G,ssd=1,serial=PROX-001
  scsi1: Storage:vm-212-disk-1,discard=on,size=1G,ssd=1,serial=PROX-002

Datasets & Users#

1. Datasets: Create HP3-10Gb-Apps-HomeDirs. Add sub-datasets Apps (Type: Apps) and HomeDirs (Type: Generic).
2. Standard User: Create user marc for SMB shares.
3. Sync User: Create backupuser. Set a home directory, uncheck Samba authentication, and do not set a password.
4. Admin Hardening: - Create user marcoue with full admin rights.
   • Upload SSH keys and enable 2FA for marcoue.
   • Disable the default truenas_admin account once verified.

SSH Hardening#

sudo nano /etc/ssh/sshd_config
# Modify/Add:
PermitRootLogin prohibit-password
PubkeyAuthentication yes

sudo systemctl restart sshd

• Services: Go to System > Services > SSH and disable “Allow Password Authentication.”

2. System & Networking Optimization#

Startup Scripts & Cron#

• Cron Shutdown: (System Settings > Advanced)
  • Command: /sbin/shutdown -h now
• Init Scripts: (Post Init)
  • Command: iperf3 -s -d
• Session Timeout: (Access > Configure) Set to 2147482.

Host Identification & Email#

• Hostname/NetBIOS: Set to HP2TrueNAS.
• Gmail OAuth/SMTP: - Use OAuth login if available.
  • SMTP: smtp.gmail.com | Port: 25 or 587.
  • Use an App Password from 1Password.

3. Data Protection & Replication#

Periodic Snapshots (Source)#

• Path: Data Protection > Periodic Snapshot Tasks.
• Settings: Uncheck “Recursive” (unless needed). Uncheck “Taking Empty Snapshot.”
• Schedule: Daily at 08:30, retention 7 days.

Replication Task (Remote Server Pull)#

1. Source: Different System.
2. Connection: New SSH (Semi-Auto).
3. Settings: Admin: marcoue, User: backupuser. Enable passwordless sudo.
4. ZFS Commands: Check “Use Sudo for ZFS Commands.”
5. Schedule: Every hour at 08:45.

4. Syncthing Deployment#

TrueNAS Scale Implementation#

1. System Settings > Advanced > Sysctl:
   • Var: fs.inotify.max_user_watches | Value: 524288.
2. Apps > Advanced: Disable “Host Path Safety Check.”
3. App Setup: Install Enterprise Version. Use Host Path for storage (e.g., /mnt/HP1-4TBSSD-Raid0/HP1Storage).

5. Hardware-Specific Configurations#

Mac Pro Auto-Restart (After Power Outage)#

cd /sys/bus/pci/devices/0000:00:1f.0
sudo chmod -R 777 config
setpci -s 0:1f.0 0xa4.b=0

Wake-on-LAN (WOL) Persistence#

Create a systemd service to ensure WOL stays active: