From 22bf55010b4a49e5097f75e6f2e05486bf2f2a25 Mon Sep 17 00:00:00 2001
From: S <islam.ahmad@outlook.com>
Date: Mon, 2 Mar 2026 08:53:23 -0500
Subject: [PATCH] fix: update usage guide to include instructions for enabling
 passwordless sudo on remote hosts

---
 USAGE_GUIDE.md | 28 ++++++++++++++++++++++++++--
 1 file changed, 26 insertions(+), 2 deletions(-)

diff --git a/USAGE_GUIDE.md b/USAGE_GUIDE.md
index 2861ec7..acb299a 100644
--- a/USAGE_GUIDE.md
+++ b/USAGE_GUIDE.md
@@ -31,7 +31,31 @@ Before running anything, confirm:
 - Macvlan container IPs are available on the LAN (not already in use)
 - If using `TLS_MODE=cloudflare`: a Cloudflare API token with Zone:DNS:Edit permission
 
-### 2. GitHub Tokens
+### 2. Passwordless sudo on remote hosts
+
+The setup and phase scripts run `sudo` commands on Unraid and Fedora over SSH (non-interactive, no TTY). If `sudo` requires a password, it will fail with: `a terminal is required to read the password`.
+
+**Enable temporarily** (on each remote host):
+
+```bash
+# SSH in interactively
+ssh user@HOST_IP
+
+# Create a drop-in sudoers file
+sudo visudo -f /etc/sudoers.d/temp-nopasswd
+# Add this line (replace YOUR_USER with the SSH username):
+YOUR_USER ALL=(ALL) NOPASSWD: ALL
+# Save and exit, then verify:
+sudo -n true && echo "OK — passwordless sudo works"
+```
+
+**Disable after migration is complete:**
+
+```bash
+sudo rm /etc/sudoers.d/temp-nopasswd
+```
+
+### 3. GitHub Tokens
 
 You need one GitHub Personal Access Token:
 
@@ -39,7 +63,7 @@ You need one GitHub Personal Access Token:
 |-------|-------|---------|
 | `GITHUB_TOKEN` | `repo` (read+write) | Migration, push mirrors, preflight validation |
 
-### 3. Configuration
+### 4. Configuration
 
 ```bash
 # Option A: Interactive wizard (recommended for first time)