truenas/INDEX.md

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

Ready to run? Execute: bash scripts/collect-truenas-config.sh

Need complete reference? Check: START-HERE-DOCS/TRUENAS_COLLECTION_README.md

API documentation? See: 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

   # 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

   export TRUENAS_API_KEY="your-api-key-here"
   # Optional: Add to ~/.bashrc or ~/.zshrc for persistence
   

3. Test API access

   bash scripts/test_truenas_api_connectivity.sh
   

4. Run first collection

   bash scripts/collect-truenas-config.sh
   

5. Review results

   cat disaster-recovery/truenas-exports/SUMMARY.md
   

Regular Use (1 minute)

# Standard collection (default level)
bash scripts/collect-truenas-config.sh

# View latest export
cat disaster-recovery/truenas-exports/SUMMARY.md

Advanced Use

# 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

# 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

# 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

# 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

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

# 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

# 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
Complete Guide	START-HERE-DOCS/TRUENAS_COLLECTION_README.md
API Reference	START-HERE-DOCS/TRUENAS_API_REFERENCE.md
Collection Script	scripts/collect-truenas-config.sh
Latest Export	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/.