Jordan Ramos
52e1822de8
Initial repository setup for TrueNAS Scale configuration management and disaster recovery. This system provides automated collection, versioning, and documentation of TrueNAS configuration state. Key components: - Configuration collection scripts with API integration - Disaster recovery exports (configs, storage, system state) - Comprehensive documentation and API reference - Sub-agent architecture for specialized operations Infrastructure protected: - Storage pools and datasets configuration - Network configuration and routing - Sharing services (NFS, SMB, iSCSI) - System tasks (snapshots, replication, cloud sync) - User and group management Security measures: - API keys managed via environment variables - Sensitive data excluded via .gitignore - No credentials committed to repository 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
315 lines
11 KiB
Markdown
315 lines
11 KiB
Markdown
# 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/.*
|