truenas/README.md

# 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**:
   ```bash
   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**:
   ```bash
   cd /home/jramos/truenas
   bash scripts/collect-truenas-config.sh
   ```

4. **Review Results**:
   ```bash
   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**:
```bash
# 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
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](INDEX.md)**: Comprehensive file navigation and command reference
- **[TRUENAS_APPS.md](TRUENAS_APPS.md)**: Docker containers and TrueNAS applications catalog with health status and network configuration
- **[START-HERE-DOCS/README-TRUENAS.md](START-HERE-DOCS/README-TRUENAS.md)**: Quick start guide
- **[START-HERE-DOCS/TRUENAS_COLLECTION_README.md](START-HERE-DOCS/TRUENAS_COLLECTION_README.md)**: Complete collection system documentation
- **[START-HERE-DOCS/TRUENAS_API_REFERENCE.md](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**:
```bash
# 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

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