# TrueNAS Scale Infrastructure Collection - File Index Welcome to your TrueNAS Scale infrastructure collection toolkit! This index will help you navigate the various files and understand what each component does. ## Quick Navigation **New to this?** Start here: **[START-HERE-DOCS/README-TRUENAS.md](START-HERE-DOCS/README-TRUENAS.md)** **Ready to run?** Execute: `bash scripts/collect-truenas-config.sh` **Need complete reference?** Check: **[START-HERE-DOCS/TRUENAS_COLLECTION_README.md](START-HERE-DOCS/TRUENAS_COLLECTION_README.md)** **API documentation?** See: **[START-HERE-DOCS/TRUENAS_API_REFERENCE.md](START-HERE-DOCS/TRUENAS_API_REFERENCE.md)** ## Repository Structure ``` truenas/ ├── scripts/ # Collection and utility scripts │ ├── collect-truenas-config.sh # Main collection script (v1.1.0) │ ├── collect-truenas-config.sh.backup # Previous version backup │ └── test_truenas_api_connectivity.sh # API connectivity tester ├── START-HERE-DOCS/ # Getting started documentation │ ├── README-TRUENAS.md # Quick reference guide │ ├── TRUENAS_COLLECTION_README.md # Complete collection system guide │ ├── TRUENAS_API_REFERENCE.md # API v2.0 endpoint reference │ ├── TRUENAS_API_FINDINGS.md # API connectivity test results │ └── TRUENAS_PROJECT_STATUS.md # Project development status ├── disaster-recovery/ # Exported configurations │ ├── truenas-exports/ # Latest export directory │ │ ├── SUMMARY.md # Collection statistics │ │ ├── configs/ # Configuration files │ │ │ ├── system/ # System configs (general, advanced) │ │ │ ├── sharing/ # NFS, SMB, iSCSI configs │ │ │ ├── network/ # Network interfaces, routes │ │ │ ├── services/ # Service status, SSH config │ │ │ ├── tasks/ # Cron, snapshots, replication │ │ │ └── users/ # User accounts and groups │ │ ├── exports/ # System state exports │ │ │ ├── system/ # System info, version │ │ │ └── storage/ # Pools, datasets, snapshots, disks │ │ └── metrics/ # Performance data (full/paranoid) │ └── truenas-exports.tar.gz # Compressed archive ├── archive-truenas/ # Historical exports ├── sub-agents/ # Agent role definitions │ ├── scribe.md # Documentation & architecture agent │ ├── backend-builder.md # Development agent │ ├── lab-operator.md # Infrastructure operations agent │ └── librarian.md # Knowledge management agent ├── troubleshooting/ # Problem resolution docs ├── CLAUDE.md # AI assistant project guidance ├── INDEX.md # This file - navigation index └── README.md # Repository overview ``` ## File Inventory ### Core Scripts | File | Location | Version | Purpose | |------|----------|---------|---------| | `collect-truenas-config.sh` | `scripts/` | v1.1.0 | Main collection engine - API-based TrueNAS config export | | `test_truenas_api_connectivity.sh` | `scripts/` | - | Tests API connectivity and authentication | **Which script should I use?** - **Standard collection**: `bash scripts/collect-truenas-config.sh` - **Custom output**: `bash scripts/collect-truenas-config.sh --output /path/to/output` - **Different level**: `bash scripts/collect-truenas-config.sh --level full` - **Custom host**: `bash scripts/collect-truenas-config.sh --host 192.168.2.151` ### Documentation | File | Location | Size | Purpose | Audience | |------|----------|------|---------|----------| | `README-TRUENAS.md` | `START-HERE-DOCS/` | 3KB | Quick reference guide | First-time users | | `TRUENAS_COLLECTION_README.md` | `START-HERE-DOCS/` | 20KB | Complete collection system guide | All users | | `TRUENAS_API_REFERENCE.md` | `START-HERE-DOCS/` | 15KB | API v2.0 endpoint reference | Power users | | `TRUENAS_API_FINDINGS.md` | `START-HERE-DOCS/` | 2.5KB | API connectivity test results | Developers | | `TRUENAS_PROJECT_STATUS.md` | `START-HERE-DOCS/` | 9KB | Project development status | Contributors | | `INDEX.md` | Root | This file | Navigation and file index | Everyone | | `CLAUDE.md` | Root | 4KB | Project context for Claude | AI assistant | | `README.md` | Root | - | Repository overview | All users | ## Typical Workflow ### First-Time Setup (5 minutes) 1. **Generate API Key** ```bash # Access TrueNAS Web UI # URL: https://192.168.2.150 # Navigate: Account → API Keys → Add # Name: homelab-collection # Copy the key (shown only once!) ``` 2. **Set environment variable** ```bash export TRUENAS_API_KEY="your-api-key-here" # Optional: Add to ~/.bashrc or ~/.zshrc for persistence ``` 3. **Test API access** ```bash bash scripts/test_truenas_api_connectivity.sh ``` 4. **Run first collection** ```bash bash scripts/collect-truenas-config.sh ``` 5. **Review results** ```bash cat disaster-recovery/truenas-exports/SUMMARY.md ``` ### Regular Use (1 minute) ```bash # Standard collection (default level) bash scripts/collect-truenas-config.sh # View latest export cat disaster-recovery/truenas-exports/SUMMARY.md ``` ### Advanced Use ```bash # Basic collection (minimal data) bash scripts/collect-truenas-config.sh --level basic # Full collection (includes SMART data) bash scripts/collect-truenas-config.sh --level full # Custom output directory bash scripts/collect-truenas-config.sh --output ./my-exports # Combined options bash scripts/collect-truenas-config.sh --level full --output ./exports ``` ## Collection Levels Explained | Level | What's Included | Use Case | API Calls | |-------|----------------|----------|-----------| | **basic** | System info, storage pools/datasets, shares, network, services | Quick overview | ~15 | | **standard** | Basic + tasks (cron, snapshots, replication) + users/groups | Regular backups (default) | ~21 | | **full** | Standard + SMART data, metrics | Comprehensive documentation | ~25 | | **paranoid** | Full + all available diagnostics | Complete disaster recovery baseline | ~30+ | **Recommendation**: Use `standard` for regular backups, `full` for monthly comprehensive snapshots. ## Latest Export Information **Most Recent Export**: 2025-12-15 23:37:14 **TrueNAS Version**: TrueNAS-SCALE-25.04.2.6 **Host**: 192.168.2.150 **Collection Level**: standard **Statistics**: - Collected: 21 items - Skipped: 1 item - Errors: 0 items ## Command Quick Reference ### Setup Commands ```bash # Generate API key (via Web UI) https://192.168.2.150 # Navigate: Account → API Keys → Add # Set environment variable export TRUENAS_API_KEY="your-api-key-here" # Make persistent (optional) echo 'export TRUENAS_API_KEY="your-api-key-here"' >> ~/.bashrc source ~/.bashrc ``` ### Collection Commands ```bash # Standard collection (default) bash scripts/collect-truenas-config.sh # Basic collection (minimal) bash scripts/collect-truenas-config.sh --level basic # Full collection (comprehensive) bash scripts/collect-truenas-config.sh --level full # Custom output location bash scripts/collect-truenas-config.sh --output /path/to/output ``` ### Review Commands ```bash # View summary cat disaster-recovery/truenas-exports/SUMMARY.md # Browse storage pools cat disaster-recovery/truenas-exports/exports/storage/pools.json | jq . # Check datasets cat disaster-recovery/truenas-exports/exports/storage/datasets.json | jq . # View NFS shares cat disaster-recovery/truenas-exports/configs/sharing/nfs.json | jq . ``` ### Help Commands ```bash # Script help bash scripts/collect-truenas-config.sh --help # Documentation cat START-HERE-DOCS/README-TRUENAS.md cat START-HERE-DOCS/TRUENAS_COLLECTION_README.md ``` ## Common Questions ### Q: Which file do I run? **A**: Run `bash scripts/collect-truenas-config.sh` from the `/home/jramos/truenas/` directory. ### Q: Do I need to set up environment variables? **A**: Yes, you must set `TRUENAS_API_KEY`. The `TRUENAS_HOST` defaults to `192.168.2.150`. ### Q: How do I get an API key? **A**: 1. Log into TrueNAS Web UI (https://192.168.2.150) 2. Navigate to: Account → API Keys 3. Click "Add" and create a new key 4. Copy the key immediately (it's only shown once) ### Q: Does this modify my TrueNAS system? **A**: No! All operations are READ-ONLY via API calls. ### Q: Can I run this on a schedule? **A**: Yes! Add to crontab: ```bash # Daily at 2 AM 0 2 * * * cd /home/jramos/truenas && bash scripts/collect-truenas-config.sh --level standard ``` ## Troubleshooting ### API Connection Issues **Problem**: `401 Unauthorized` **Solutions**: 1. Verify API key is set: `echo $TRUENAS_API_KEY` 2. Check API key hasn't expired in TrueNAS Web UI 3. Regenerate API key if necessary --- **Problem**: `Connection refused` or timeout **Solutions**: 1. Verify TrueNAS is reachable: `ping 192.168.2.150` 2. Check HTTPS service: `curl -k https://192.168.2.150` 3. Verify firewall allows HTTPS (port 443) --- **Problem**: Some items show as "Skipped" **Explanation**: Normal if features aren't configured (iSCSI, cloud sync, etc.) ## Integration with Homelab This TrueNAS collection complements your Proxmox homelab at 192.168.2.200: **Proxmox Homelab**: VMs, LXC containers, service hosting **TrueNAS Scale**: Network-attached storage, media server, backup target ```bash # Proxmox collection cd /home/jramos/homelab bash scripts/crawlers-exporters/collect.sh # TrueNAS collection cd /home/jramos/truenas bash scripts/collect-truenas-config.sh ``` ## Quick Links Summary | Resource | Location | |----------|----------| | **Start Here** | [START-HERE-DOCS/README-TRUENAS.md](START-HERE-DOCS/README-TRUENAS.md) | | **Complete Guide** | [START-HERE-DOCS/TRUENAS_COLLECTION_README.md](START-HERE-DOCS/TRUENAS_COLLECTION_README.md) | | **API Reference** | [START-HERE-DOCS/TRUENAS_API_REFERENCE.md](START-HERE-DOCS/TRUENAS_API_REFERENCE.md) | | **Collection Script** | [scripts/collect-truenas-config.sh](scripts/collect-truenas-config.sh) | | **Latest Export** | [disaster-recovery/truenas-exports/](disaster-recovery/truenas-exports/) | | **TrueNAS Web UI** | https://192.168.2.150 | --- **Last Updated**: 2025-12-15 **TrueNAS Version**: TrueNAS-SCALE-25.04.2.6 **Collection Script**: v1.1.0 **Repository Version**: 1.0.0 --- *For questions, issues, or contributions, refer to the project documentation in START-HERE-DOCS/.*