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

292
README.md Normal file
View File

@@ -0,0 +1,292 @@
# TrueNAS Scale Infrastructure Repository
Version-controlled infrastructure configuration for TrueNAS Scale storage environment.
## Overview
This repository contains configuration files, scripts, and documentation for managing a TrueNAS Scale 25.04.2.6 storage server. The system uses API-based collection to capture infrastructure state, enabling disaster recovery planning and configuration management.
## Infrastructure Components
### TrueNAS Host
- **Host**: 192.168.2.150
- **Version**: TrueNAS-SCALE-25.04.2.6
- **Architecture**: Single-node storage server
- **Primary Use**: Network-attached storage, media server
### Storage Pools
- **Vauly**: ZFS mirror pool (primary storage)
- Status: Monitor via `disaster-recovery/truenas-exports/exports/storage/pools.json`
### Sharing Services
- **NFS**: Network File System shares for Unix/Linux clients
- **SMB**: Samba/CIFS shares for Windows compatibility
- **iSCSI**: Block-level storage targets for advanced use cases
## Repository Structure
```
truenas/
├── scripts/ # Collection and utility scripts
│ └── collect-truenas-config.sh # Main API-based collection (v1.1.0)
├── disaster-recovery/ # Exported configurations
│ └── truenas-exports/ # Latest configuration snapshot
├── START-HERE-DOCS/ # Documentation library
│ ├── README-TRUENAS.md # Quick start guide
│ ├── TRUENAS_COLLECTION_README.md # Complete system guide
│ └── TRUENAS_API_REFERENCE.md # API v2.0 documentation
├── sub-agents/ # AI agent role definitions
├── troubleshooting/ # Problem resolution docs
├── archive-truenas/ # Historical exports
├── CLAUDE.md # AI assistant guidance
├── INDEX.md # Comprehensive documentation index
└── README.md # This file
```
## Quick Start
### Prerequisites
- Network access to TrueNAS at 192.168.2.150
- TrueNAS API key (generate via Web UI)
- Basic familiarity with command line
- WSL2 (if on Windows) or native Linux environment
### Initial Setup
1. **Generate API Key**:
- Access TrueNAS Web UI: 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: Make persistent
echo 'export TRUENAS_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc
```
3. **Run First Collection**:
```bash
cd /home/jramos/truenas
bash scripts/collect-truenas-config.sh
```
4. **Review Results**:
```bash
cat disaster-recovery/truenas-exports/SUMMARY.md
```
## Scripts
### collect-truenas-config.sh (v1.1.0)
API-based configuration collection script with four collection levels:
| Level | Description | Use Case |
|-------|-------------|----------|
| **basic** | System info, storage, shares, network, services | Quick snapshots |
| **standard** | Basic + tasks and users | Regular backups (default) |
| **full** | Standard + SMART data | Comprehensive docs |
| **paranoid** | Everything available | Complete DR baseline |
**Usage Examples**:
```bash
# Standard collection (default)
bash scripts/collect-truenas-config.sh
# Full collection with SMART data
bash scripts/collect-truenas-config.sh --level full
# Custom output directory
bash scripts/collect-truenas-config.sh --output /path/to/output
# Different host
bash scripts/collect-truenas-config.sh --host 192.168.2.151
```
**Help**:
```bash
bash scripts/collect-truenas-config.sh --help
```
## API-Based Collection
Unlike traditional SSH-based configuration dumps, this system uses the **TrueNAS Scale REST API v2.0** for structured data collection:
**Advantages**:
- ✓ Structured JSON output (machine-parseable)
- ✓ Read-only operations (zero risk)
- ✓ Fine-grained access control via API keys
- ✓ No SSH key management required
- ✓ Standardized across TrueNAS versions
**Collected Data**:
- System information and version
- Storage pools, datasets, snapshots
- NFS, SMB, iSCSI configurations
- Network interfaces and routes
- Service status and configurations
- Scheduled tasks and replication
- User accounts and groups
- SMART data (full/paranoid levels)
## Usage Guides
- **[INDEX.md](INDEX.md)**: Comprehensive file navigation and command reference
- **[START-HERE-DOCS/README-TRUENAS.md](START-HERE-DOCS/README-TRUENAS.md)**: Quick start guide
- **[START-HERE-DOCS/TRUENAS_COLLECTION_README.md](START-HERE-DOCS/TRUENAS_COLLECTION_README.md)**: Complete collection system documentation
- **[START-HERE-DOCS/TRUENAS_API_REFERENCE.md](START-HERE-DOCS/TRUENAS_API_REFERENCE.md)**: API v2.0 endpoint reference
## Security Notes
### API Key Management
- API keys provide full access to TrueNAS API
- Store securely (environment variables, password managers)
- Never commit API keys to version control
- Rotate keys periodically
- Use dedicated keys for automation
### Data Sensitivity
- Exports contain: IP addresses, hostnames, user accounts, share paths
- Review exports before sharing publicly
- Consider sanitizing sensitive data for external distribution
- User passwords are never collected (TrueNAS API doesn't expose them)
### SSL Certificates
- TrueNAS uses self-signed certificates by default
- Collection script uses `--insecure` flag for curl
- Consider installing proper SSL certificates for production
## Disaster Recovery
### Configuration Exports
- Timestamped snapshots in `disaster-recovery/`
- JSON format for programmatic access
- Human-readable SUMMARY.md for quick review
- Compressed archives for efficient storage
### Recovery Process
1. Review latest export in `disaster-recovery/truenas-exports/`
2. Reinstall TrueNAS Scale on new hardware
3. Recreate storage pools using pool topology from exports
4. Restore shares, services, and tasks from JSON configs
5. Reimport datasets from backup storage
**Note**: Exports contain *configurations*, not *data*. Actual data recovery requires separate backup strategy (snapshots, replication, external backups).
## Backup Strategy
**Configuration Backups** (this repository):
- Automated via collection scripts
- Version-controlled with git
- Stored in disaster-recovery/ directory
- Run weekly or after significant changes
**Data Backups** (separate process):
- ZFS snapshots for local protection
- Replication to remote TrueNAS or backup server
- Cloud sync for critical data
- Regular testing of restore procedures
## Integration with Homelab
This TrueNAS repository complements the Proxmox homelab infrastructure:
**Proxmox Homelab** (`/home/jramos/homelab`):
- Virtualization platform (192.168.2.200)
- VMs and LXC containers
- Service hosting (n8n, NetBox, Monitoring)
- Development environment
**TrueNAS Scale** (`/home/jramos/truenas`):
- Network-attached storage (192.168.2.150)
- Media server storage
- Backup target for VMs
- Data archival and snapshots
**Unified Documentation**:
```bash
# Collect Proxmox configuration
cd /home/jramos/homelab
bash scripts/crawlers-exporters/collect.sh
# Collect TrueNAS configuration
cd /home/jramos/truenas
bash scripts/collect-truenas-config.sh
```
## Common Commands
```bash
# Run standard collection
bash scripts/collect-truenas-config.sh
# View latest summary
cat disaster-recovery/truenas-exports/SUMMARY.md
# Check storage pools
cat disaster-recovery/truenas-exports/exports/storage/pools.json | jq .
# Review shares
cat disaster-recovery/truenas-exports/configs/sharing/*.json | jq .
# Test API connectivity
curl -X GET "https://192.168.2.150/api/v2.0/system/version" \
-H "Authorization: Bearer ${TRUENAS_API_KEY}" \
--insecure | jq .
```
## Contributing
This is a personal infrastructure repository. If using as a template:
1. Fork the repository
2. Update `TRUENAS_HOST` for your environment
3. Generate your own API key
4. Customize collection scripts as needed
5. Update documentation to match your setup
## Documentation
Comprehensive documentation available in:
- **CLAUDE.md**: AI assistant context and repository guidelines
- **INDEX.md**: Complete file navigation and command reference
- **START-HERE-DOCS/**: Getting started guides and API documentation
## Troubleshooting
### API Connection Issues
```bash
# Test connectivity
curl -k https://192.168.2.150
# Test API authentication
curl -X GET "https://192.168.2.150/api/v2.0/system/version" \
-H "Authorization: Bearer ${TRUENAS_API_KEY}" \
--insecure
```
### Collection Issues
- Verify `TRUENAS_API_KEY` is set: `echo $TRUENAS_API_KEY`
- Check TrueNAS is reachable: `ping 192.168.2.150`
- Review logs in collection output
- Some "skipped" items are normal (unused features)
## License
This is a personal infrastructure repository. Use at your own risk.
## Support
For questions about:
- **TrueNAS**: https://www.truenas.com/docs/scale/
- **This Repository**: See [INDEX.md](INDEX.md) and START-HERE-DOCS/
---
**Last Updated**: 2025-12-15
**TrueNAS Version**: TrueNAS-SCALE-25.04.2.6
**Collection Script**: v1.1.0
**Infrastructure**: Single-node storage server at 192.168.2.150