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.

Synology Administration Guide#

1 Syncthing Deployment#

1.1 Synology DSM Implementation (Docker)#

1. Inotify Limit:

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

2. User IDs: Use Task Scheduler to run id > /volume1/docker/id.txt to find UID/GID (e.g., 1027/100).
3. Docker Compose Highlights:

   environment:
     - PUID=1027
     - PGID=100
     - TZ=America/New_York
   volumes:
     - ./config:/config
     - /volume2/HP3Storage:/volume2/HP3Storage

1.2 Standard .stignore Patterns#

Create a .stignore file in the root of the sync folder:

(?i)#recycle
@eaDir
.DS_Store
.stfolder
.stignore
$RECYCLE.BIN
Thumbs.db
Desktop.ini
.SynologyWorkingDirectory

2 Storage & Maintenance Commands#

2.1 iPerf3#

sudo -i
synogear install
iperf3 -s -p 11111

2.2 Locked Folder Cleanup#

Remove Synology metadata directories when cleaning up a locked folder:

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:

UPS Tools (Network UPS Tools) Setup Guide#

This guide covers the installation of a NUT Server on a central VM (230) and the configuration of NUT Clients (Proxmox nodes) to ensure graceful shutdowns across your infrastructure.

1. NUT Server Installation (VM 230)#

1.1. Prerequisites & Software#

# Verify USB visibility (Ensure USB passthrough is configured in Proxmox)
lsusb

# Install NUT suite
apt update && apt install nut nut-client nut-server -y

1.2. Ubuntu 24.04 (NUT 2.8.1) Library Fix#

If USB scanning fails on Ubuntu 24.04, create the following symlinks: