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:

   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:

   cd /home/jramos/truenas
   bash scripts/collect-truenas-config.sh
   

4. Review Results:

   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:

# 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 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: Comprehensive file navigation and command reference
• TRUENAS_APPS.md: Docker containers and TrueNAS applications catalog with health status and network configuration
• START-HERE-DOCS/README-TRUENAS.md: Quick start guide
• START-HERE-DOCS/TRUENAS_COLLECTION_README.md: Complete collection system documentation
• 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:

# 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

# 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

# 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 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