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](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](START-HERE-DOCS/TRUENAS_COLLECTION_README.md)**

**API documentation?** See: **[START-HERE-DOCS/TRUENAS_API_REFERENCE.md](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**
   ```bash
   # 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**
   ```bash
   export TRUENAS_API_KEY="your-api-key-here"
   # Optional: Add to ~/.bashrc or ~/.zshrc for persistence
   ```

3. **Test API access**
   ```bash
   bash scripts/test_truenas_api_connectivity.sh
   ```

4. **Run first collection**
   ```bash
   bash scripts/collect-truenas-config.sh
   ```

5. **Review results**
   ```bash
   cat disaster-recovery/truenas-exports/SUMMARY.md
   ```

### Regular Use (1 minute)

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

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

### Advanced Use

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

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

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

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

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

```bash
# 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](START-HERE-DOCS/README-TRUENAS.md) |
| **Complete Guide** | [START-HERE-DOCS/TRUENAS_COLLECTION_README.md](START-HERE-DOCS/TRUENAS_COLLECTION_README.md) |
| **API Reference** | [START-HERE-DOCS/TRUENAS_API_REFERENCE.md](START-HERE-DOCS/TRUENAS_API_REFERENCE.md) |
| **Collection Script** | [scripts/collect-truenas-config.sh](scripts/collect-truenas-config.sh) |
| **Latest Export** | [disaster-recovery/truenas-exports/](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/.*