Initial commit — OpenClaw VM infrastructure

- ansible/: VM provisioning playbooks and roles
  - provision-vm.yml: create KVM VM from Ubuntu cloud image
  - install.yml: install OpenClaw on guest (upstream)
  - customize.yml: swappiness, virtiofs fstab, linger
  - roles/vm/: libvirt domain XML, cloud-init templates
  - inventory.yml + host_vars/zap.yml: zap instance config
- backup-openclaw-vm.sh: daily rsync + MinIO upload
- restore-openclaw-vm.sh: full redeploy from scratch
- README.md: full operational documentation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

ansible/docs/troubleshooting.md

@@ -0,0 +1,160 @@
+---
+title: Troubleshooting
+description: Common issues and solutions
+---
+
+# Troubleshooting
+
+## Container Can't Reach Internet
+
+**Symptom**: OpenClaw can't connect to WhatsApp/Telegram
+
+**Check**:
+```bash
+# Test from container
+sudo docker exec openclaw ping -c 3 8.8.8.8
+
+# Check UFW allows outbound
+sudo ufw status verbose | grep OUT
+```
+
+**Solution**:
+```bash
+# Verify DOCKER-USER allows established connections
+sudo iptables -L DOCKER-USER -n -v
+
+# Restart Docker + Firewall
+sudo systemctl restart docker
+sudo ufw reload
+sudo systemctl restart openclaw
+```
+
+## Port Already in Use
+
+**Symptom**: Port 3000 conflict
+
+**Solution**:
+```bash
+# Find what's using port 3000
+sudo ss -tlnp | grep 3000
+
+# Change OpenClaw port
+sudo nano /opt/openclaw/docker-compose.yml
+# Change: "127.0.0.1:3001:3000"
+
+sudo systemctl restart openclaw
+```
+
+## Firewall Lockout
+
+**Symptom**: Can't SSH after installation
+
+**Solution** (via console/rescue mode):
+```bash
+# Disable UFW temporarily
+sudo ufw disable
+
+# Check SSH rule exists
+sudo ufw status numbered
+
+# Re-add SSH rule
+sudo ufw allow 22/tcp
+
+# Re-enable
+sudo ufw enable
+```
+
+## Container Won't Start
+
+**Check logs**:
+```bash
+# Systemd logs
+sudo journalctl -u openclaw -n 50
+
+# Docker logs
+sudo docker logs openclaw
+
+# Compose status
+sudo docker compose -f /opt/openclaw/docker-compose.yml ps
+```
+
+**Common fixes**:
+```bash
+# Rebuild image
+cd /opt/openclaw
+sudo docker compose build --no-cache
+sudo systemctl restart openclaw
+
+# Check permissions
+sudo chown -R openclaw:openclaw /home/openclaw/.openclaw
+```
+
+## Verify Docker Isolation
+
+**Test that external ports are blocked**:
+```bash
+# Start test container
+sudo docker run -d -p 80:80 --name test-nginx nginx
+
+# From EXTERNAL machine (should fail):
+curl http://YOUR_SERVER_IP:80
+
+# From SERVER (should work):
+curl http://localhost:80
+
+# Cleanup
+sudo docker rm -f test-nginx
+```
+
+## UFW Status Shows Inactive
+
+**Fix**:
+```bash
+# Enable UFW
+sudo ufw enable
+
+# Reload rules
+sudo ufw reload
+
+# Verify
+sudo ufw status verbose
+```
+## Ansible Playbook Fails
+
+### Failed to set permissions on temporary files (Become Issue)
+
+**Symptom**: `fatal: [host]: FAILED! => {"msg": "Failed to set permissions on the temporary files Ansible needs to create when becoming an unprivileged user..."}`
+
+**Cause**: This happens when connecting as an unprivileged user (e.g., `ansible`) and using `become_user` to switch to another unprivileged user (e.g., `openclaw`). Ansible struggles to share temporary module files between them if the filesystem doesn't support POSIX ACLs.
+
+**Solution**:
+Enable **Ansible Pipelining** in your `ansible.cfg`. This executes modules via stdin without creating temporary files.
+
+```ini
+[defaults]
+pipelining = True
+```
+
+Alternatively, if you cannot use pipelining, you can allow world-readable temporary files (less secure):
+```ini
+[defaults]
+allow_world_readable_tmpfiles = True
+```
+
+### Collection missing
+...
+```bash
+ansible-galaxy collection install -r requirements.yml
+```
+
+**Permission denied**:
+```bash
+# Run with --ask-become-pass
+ansible-playbook playbook.yml --ask-become-pass
+```
+
+**Docker daemon not running**:
+```bash
+sudo systemctl start docker
+# Re-run playbook
+```