truenas/START-HERE-DOCS/README-TRUENAS.md

TrueNAS Scale Collection System - Quick Reference

Status: Foundation Phase Complete
Server: 192.168.2.150
Created: 2025-12-14

---

Documentation Files

This directory contains the complete TrueNAS Scale collection system documentation:

File	Size	Description
TRUENAS_COLLECTION_README.md	20KB	Complete usage guide, endpoints, examples
TRUENAS_API_REFERENCE.md	15KB	API v2.0 reference with working examples
TRUENAS_API_FINDINGS.md	2.5KB	API connectivity test results
TRUENAS_PROJECT_STATUS.md	9KB	Project status and next steps
test_truenas_api_connectivity.sh	Script	API connectivity tester

---

Quick Start

1. Generate API Key

# Access TrueNAS Web UI
https://192.168.2.150

# Navigate: Account → API Keys → Add
# Name: homelab-collection
# Save and copy the key (shown only once)

2. Test API Access

# Set environment variable
export TRUENAS_API_KEY="your-api-key-here"

# Test connection
curl -X GET "https://192.168.2.150/api/v2.0/system/version" \
  -H "Authorization: Bearer ${TRUENAS_API_KEY}" \
  -H "Content-Type: application/json" \
  --insecure | jq .

Expected output:

{
  "fullversion": "TrueNAS-SCALE-XX.XX.X",
  "version": "XX.XX.X"
}

3. Run Connectivity Test

# Run the test script
./test_truenas_api_connectivity.sh

# Check results
cat /tmp/truenas_api_test_*.log

---

What's Been Tested

✅ Network Connectivity: Host reachable (2.7ms latency)
✅ HTTPS Port 443: Accessible
✅ API Endpoint: Responds correctly
✅ Authentication: Required (401 response - expected)
✅ SSL Certificate: Self-signed (requires --insecure flag)

---

API Implementation Details

Base URL: https://192.168.2.150/api/v2.0

Authentication:

Authorization: Bearer <API_KEY>
Content-Type: application/json

SSL Handling:

curl --insecure  # or -k flag for self-signed certificates

---

Key API Endpoints

System Information

• GET /system/info - Hardware and version
• GET /system/version - TrueNAS version
• GET /system/general - General configuration

Storage

• GET /pool - All pools
• GET /pool/dataset - All datasets
• GET /disk - Disk inventory
• GET /disk/temperature - Disk temperatures

Sharing

• GET /sharing/nfs - NFS shares
• GET /sharing/smb - SMB shares

Services

• GET /service - All service statuses

Full endpoint reference: See TRUENAS_API_REFERENCE.md

---

Collection Script (Pending)

Target: /home/jramos/homelab/scripts/crawlers-exporters/collect-truenas-config.sh

Features (Planned):

• Hybrid API + SSH collection
• 4 collection levels (basic, standard, full, paranoid)
• Organized directory structure
• Sanitization and security
• Logging and error handling
• Compression support

Specification: Fully documented by lab-operator and backend-builder agents

---

Directory Structure (Planned)

truenas-export-YYYYMMDD-HHMMSS/
├── README.md
├── SUMMARY.md
├── collection.log
├── configs/
│   ├── system/
│   ├── storage/
│   ├── sharing/
│   ├── network/
│   ├── services/
│   └── tasks/
├── exports/
│   ├── storage/
│   ├── system/
│   ├── network/
│   └── logs/
└── metrics/

---

Next Steps

Immediate (You)

1. Generate API key in TrueNAS UI
2. Test authenticated API call
3. Verify access to all required endpoints

Development (Future)

1. Implement collection script
2. Test all collection levels
3. Integrate with homelab workflow
4. Add to cron for automation
5. Set up monitoring dashboards

---

Agent Collaboration Summary

Agent	Task	Status	Output
lab-operator	API connectivity testing	✅ Complete	Test script + findings
scribe	Documentation	✅ Complete	README + API reference
backend-builder	Collection script	⏳ Pending	Specification ready

---

Integration with Homelab

Current Proxmox Integration:

# Proxmox mounts TrueNAS NFS export
nfs: iso-share
    export /mnt/Vauly/iso-vault
    path /mnt/pve/iso-share
    server 192.168.2.150
    content iso

Planned Unified Collection:

homelab-exports/
├── export-YYYYMMDD/
│   ├── proxmox-export/    # From collect-homelab-config.sh
│   └── truenas-export/    # From collect-truenas-config.sh (pending)

---

Troubleshooting

Problem: API returns 401 Unauthorized
Solution: Verify API key is set: echo $TRUENAS_API_KEY

Problem: SSL certificate error
Solution: Use --insecure flag or install CA certificate

Problem: Connection timeout
Solution: Verify network connectivity: ping 192.168.2.150

Full troubleshooting guide: See TRUENAS_COLLECTION_README.md

---

Reference Links

Documentation:

• Complete README: TRUENAS_COLLECTION_README.md
• API Reference: TRUENAS_API_REFERENCE.md
• Project Status: TRUENAS_PROJECT_STATUS.md
• Test Results: TRUENAS_API_FINDINGS.md

Official Resources:

• TrueNAS Docs: https://www.truenas.com/docs/scale/
• API Docs: https://www.truenas.com/docs/api/
• Forums: https://forums.truenas.com/

Related Homelab Files:

• Proxmox Collection: collect-homelab-config.sh
• Homelab Status: /home/jramos/homelab/CLAUDE_STATUS.md

---

Summary

Foundation Phase: COMPLETE ✅

Achievements:

• API connectivity validated
• Authentication method confirmed
• Comprehensive documentation (35KB total)
• Collection approach designed
• Integration strategy defined

Ready for Implementation:

1. Generate API key
2. Test authenticated access
3. Implement collection script
4. Integrate with homelab workflow

---

Last Updated: 2025-12-14
Maintained By: Main Agent (coordination)
Project: TrueNAS Scale Collection System