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

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

```bash
# 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:
```json
{
  "fullversion": "TrueNAS-SCALE-XX.XX.X",
  "version": "XX.XX.X"
}
```

### 3. Run Connectivity Test

```bash
# 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:**
```bash
Authorization: Bearer <API_KEY>
Content-Type: application/json
```

**SSL Handling:**
```bash
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