jramos/truenas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(infrastructure): initialize TrueNAS Scale infrastructure collection system

Browse Source 
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>
This commit is contained in:
Jordan Ramos
2025-12-16 08:03:33 -07:00
commit 52e1822de8
37 changed files with 40881 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

314
INDEX.md Normal file
View File

@@ -0,0 +1,314 @@
# 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/.*