jramos/truenas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
truenas/START-HERE-DOCS/TRUENAS_API_REFERENCE.md
Jordan Ramos 52e1822de8 feat(infrastructure): initialize TrueNAS Scale infrastructure collection system 
Initial repository setup for TrueNAS Scale configuration management and
disaster recovery. This system provides automated collection, versioning,
and documentation of TrueNAS configuration state.

Key components:
- Configuration collection scripts with API integration
- Disaster recovery exports (configs, storage, system state)
- Comprehensive documentation and API reference
- Sub-agent architecture for specialized operations

Infrastructure protected:
- Storage pools and datasets configuration
- Network configuration and routing
- Sharing services (NFS, SMB, iSCSI)
- System tasks (snapshots, replication, cloud sync)
- User and group management

Security measures:
- API keys managed via environment variables
- Sensitive data excluded via .gitignore
- No credentials committed to repository

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2025-12-16 08:03:33 -07:00

14 KiB
Raw Permalink Blame History

TrueNAS Scale API v2.0 Reference

Target Server: 192.168.2.150 API Version: 2.0 Documentation Type: Collection-Focused Reference

Table of Contents

  1. Authentication
  2. API Basics
  3. System Endpoints
  4. Storage Endpoints
  5. Sharing Endpoints
  6. Network Endpoints
  7. Service Endpoints
  8. Task Endpoints
  9. User Management
  10. Error Codes
  11. Examples

Authentication

API Key Generation

Method 1: Web UI

  1. Log in to TrueNAS Scale: https://192.168.2.150
  2. Navigate to: Account → API Keys
  3. Click Add
  4. Configure:
    • Name: homelab-collection
    • Username: admin (or your user)
    • Expiration: Optional
  5. Click Save
  6. IMPORTANT: Copy the key immediately (shown only once)

Method 2: CLI (if logged in via SSH)

midclt call auth.generate_token 120  # 120 seconds validity

Authentication Headers

All API requests require:

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

Example:

curl -X GET "https://192.168.2.150/api/v2.0/system/info" \
  -H "Authorization: Bearer 1-YourAPIKeyHere" \
  -H "Content-Type: application/json" \
  --insecure  # Only if using self-signed certificate

Testing Authentication

# Test 1: Get system version (minimal permissions)
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

# Expected response:
# {"fullversion": "TrueNAS-SCALE-23.10.1", "version": "23.10.1"}

# Test 2: Get system info (more detailed)
curl -X GET "https://192.168.2.150/api/v2.0/system/info" \
  -H "Authorization: Bearer ${TRUENAS_API_KEY}" \
  -H "Content-Type: application/json" \
  --insecure | jq .

API Basics

Base URL

https://192.168.2.150/api/v2.0

Response Format

All responses are JSON-formatted.

Success Response:

{
  "id": 1,
  "name": "example",
  "status": "SUCCESS"
}

Error Response:

{
  "error": "Error message",
  "errname": "EINVAL",
  "extra": null
}

Query Parameters

Filtering:

# Get datasets with specific properties
curl -X GET "https://192.168.2.150/api/v2.0/pool/dataset?name=Vauly" \
  -H "Authorization: Bearer ${TRUENAS_API_KEY}" \
  --insecure

HTTP Methods

Method Purpose Idempotent Collection Use
GET Retrieve data Yes Primary method
POST Create resource No Not used
PUT Update resource Yes Not used
DELETE Remove resource Yes Not used

Collection scripts use GET only (read-only operations).

System Endpoints

GET /api/v2.0/system/info

Description: Get comprehensive system information

Request:

curl -X GET "https://192.168.2.150/api/v2.0/system/info" \
  -H "Authorization: Bearer ${TRUENAS_API_KEY}" \
  --insecure

Response:

{
  "version": "TrueNAS-SCALE-23.10.1",
  "hostname": "truenas",
  "physmem": 68719476736,
  "model": "AMD Ryzen",
  "cores": 16,
  "physical_cores": 8,
  "loadavg": [0.5, 0.6, 0.7],
  "uptime": "10 days, 5:30:15",
  "uptime_seconds": 896415.0,
  "boottime": "2025-12-04T10:30:00",
  "datetime": "2025-12-14T15:30:15",
  "timezone": "America/New_York"
}

Key Fields:

  • version: TrueNAS Scale version
  • physmem: Physical memory in bytes
  • cores: Total CPU cores
  • uptime_seconds: System uptime
  • loadavg: 1, 5, 15-minute load averages

GET /api/v2.0/system/version

Description: Get TrueNAS version string

Request:

curl -X GET "https://192.168.2.150/api/v2.0/system/version" \
  -H "Authorization: Bearer ${TRUENAS_API_KEY}" \
  --insecure

Response:

{
  "fullversion": "TrueNAS-SCALE-23.10.1",
  "version": "23.10.1"
}

GET /api/v2.0/system/advanced

Description: Get advanced system settings

Response includes:

  • Boot scrub interval
  • Console settings
  • Power management
  • Syslog configuration
  • Debug settings

GET /api/v2.0/system/general

Description: Get general system configuration

Response includes:

  • Web UI settings (ports, protocols)
  • Timezone and language
  • Keyboard map
  • Certificate configuration

Storage Endpoints

GET /api/v2.0/pool

Description: List all storage pools

Request:

curl -X GET "https://192.168.2.150/api/v2.0/pool" \
  -H "Authorization: Bearer ${TRUENAS_API_KEY}" \
  --insecure

Response:

[
  {
    "id": 1,
    "name": "Vauly",
    "guid": "1234567890123456789",
    "status": "ONLINE",
    "path": "/mnt/Vauly",
    "scan": {
      "function": "SCRUB",
      "state": "FINISHED",
      "start_time": "2025-12-10T02:00:00",
      "end_time": "2025-12-10T06:30:00",
      "percentage": 100.0,
      "errors": 0
    },
    "is_decrypted": true,
    "healthy": true,
    "size": 3221225472000,
    "allocated": 67108864000,
    "free": 3154116608000,
    "fragmentation": "1%",
    "topology": {
      "data": [],
      "cache": [],
      "log": [],
      "spare": []
    }
  }
]

Key Fields:

  • name: Pool name (e.g., "Vauly")
  • status: Pool health status
  • healthy: Boolean health indicator
  • size: Total pool size in bytes
  • free: Available space in bytes
  • scan: Last scrub information

GET /api/v2.0/pool/dataset

Description: List all datasets and zvols

Request:

curl -X GET "https://192.168.2.150/api/v2.0/pool/dataset" \
  -H "Authorization: Bearer ${TRUENAS_API_KEY}" \
  --insecure

Response:

[
  {
    "id": "Vauly/iso-vault",
    "type": "FILESYSTEM",
    "name": "Vauly/iso-vault",
    "pool": "Vauly",
    "encrypted": false,
    "mountpoint": "/mnt/Vauly/iso-vault",
    "compression": {
      "parsed": "lz4",
      "value": "lz4"
    },
    "used": {
      "parsed": 67108864000,
      "value": "62.5G"
    },
    "available": {
      "parsed": 3154116608000,
      "value": "2.9T"
    }
  }
]

Query specific dataset:

curl -X GET "https://192.168.2.150/api/v2.0/pool/dataset?id=Vauly/iso-vault" \
  -H "Authorization: Bearer ${TRUENAS_API_KEY}" \
  --insecure

GET /api/v2.0/disk

Description: Get disk inventory

Response includes:

  • Disk serial numbers
  • Model information
  • Size and type (HDD/SSD)
  • Current pool assignment
  • SMART status
  • Temperature readings

GET /api/v2.0/disk/temperature

Description: Get current disk temperatures

Request:

curl -X GET "https://192.168.2.150/api/v2.0/disk/temperature" \
  -H "Authorization: Bearer ${TRUENAS_API_KEY}" \
  --insecure

Response:

{
  "sda": 35,
  "sdb": 32,
  "sdc": 34,
  "sdd": 36
}

GET /api/v2.0/pool/scrub

Description: Get scrub status and history

Response includes:

  • Current scrub state
  • Start/end times
  • Bytes processed
  • Error count
  • Completion percentage

GET /api/v2.0/smart/test/results

Description: Get SMART test results for all disks

Response includes:

  • Test type (short/long)
  • Test status
  • Completion time
  • Any errors found

Sharing Endpoints

GET /api/v2.0/sharing/nfs

Description: Get all NFS share configurations

Request:

curl -X GET "https://192.168.2.150/api/v2.0/sharing/nfs" \
  -H "Authorization: Bearer ${TRUENAS_API_KEY}" \
  --insecure

Response:

[
  {
    "id": 1,
    "path": "/mnt/Vauly/iso-vault",
    "comment": "ISO storage for Proxmox",
    "networks": ["192.168.2.0/24"],
    "hosts": [],
    "ro": false,
    "maproot_user": "root",
    "maproot_group": "root",
    "security": ["SYS"],
    "enabled": true
  }
]

GET /api/v2.0/sharing/smb

Description: Get all SMB/CIFS share configurations

Response includes:

  • Share name and path
  • Access permissions
  • Guest access settings
  • Host allow/deny lists
  • Enable status

GET /api/v2.0/sharing/iscsi/target

Description: Get iSCSI target configurations

GET /api/v2.0/sharing/iscsi/extent

Description: Get iSCSI extent configurations

Network Endpoints

GET /api/v2.0/interface

Description: Get network interface configurations

Response includes:

  • Interface name and type
  • IP addresses (IPv4/IPv6)
  • MTU settings
  • Link state
  • DHCP configuration

GET /api/v2.0/network/configuration

Description: Get global network configuration

Response includes:

  • Hostname and domain
  • Default gateway
  • DNS servers
  • Service announcement settings

GET /api/v2.0/staticroute

Description: Get static route configurations

Service Endpoints

GET /api/v2.0/service

Description: Get status of all services

Request:

curl -X GET "https://192.168.2.150/api/v2.0/service" \
  -H "Authorization: Bearer ${TRUENAS_API_KEY}" \
  --insecure

Response:

[
  {
    "id": 1,
    "service": "ssh",
    "enable": true,
    "state": "RUNNING",
    "pids": [1234]
  },
  {
    "id": 2,
    "service": "nfs",
    "enable": true,
    "state": "RUNNING",
    "pids": [5678, 5679]
  }
]

GET /api/v2.0/ssh

Description: Get SSH service configuration

Response includes:

  • TCP port
  • Root login settings
  • Password authentication
  • SFTP log settings

Task Endpoints

GET /api/v2.0/cronjob

Description: Get cron job configurations

GET /api/v2.0/pool/snapshottask

Description: Get snapshot task configurations

GET /api/v2.0/rsynctask

Description: Get rsync task configurations

GET /api/v2.0/cloudsync

Description: Get cloud sync task configurations

GET /api/v2.0/replication

Description: Get ZFS replication task configurations

User Management

GET /api/v2.0/user

Description: Get all user accounts

Response includes:

  • Username and UID
  • Home directory
  • Shell
  • Group memberships
  • SSH public keys

GET /api/v2.0/group

Description: Get all groups

Error Codes

HTTP Status Codes

Code Meaning Description
200 OK Request successful
400 Bad Request Invalid request syntax
401 Unauthorized Invalid or missing API key
403 Forbidden Insufficient permissions
404 Not Found Resource doesn't exist
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server-side error

TrueNAS Error Names

Error Name Description Common Cause
EINVAL Invalid argument Wrong parameter type or value
ENOENT No such file or directory Resource doesn't exist
EACCES Permission denied Insufficient permissions
EFAULT General fault Internal middleware error

Examples

Complete Health Check Script

#!/bin/bash
# truenas-health-check.sh

TRUENAS_HOST="192.168.2.150"
TRUENAS_API_KEY="${TRUENAS_API_KEY:?API key not set}"

API_BASE="https://${TRUENAS_HOST}/api/v2.0"
CURL_OPTS="-s -H 'Authorization: Bearer ${TRUENAS_API_KEY}' --insecure"

echo "=== TrueNAS Health Check ==="

# System version
echo "System Version:"
curl ${CURL_OPTS} "${API_BASE}/system/version" | jq -r '.fullversion'

# Pool status
echo "Pool Status:"
curl ${CURL_OPTS} "${API_BASE}/pool" | \
  jq -r '.[] | "\(.name): \(.status) (Healthy: \(.healthy))"'

# Disk temperatures
echo "Disk Temperatures:"
curl ${CURL_OPTS} "${API_BASE}/disk/temperature" | \
  jq -r 'to_entries[] | "\(.key): \(.value)°C"'

# Service status
echo "Service Status:"
curl ${CURL_OPTS} "${API_BASE}/service" | \
  jq -r '.[] | select(.enable == true) | "\(.service): \(.state)"'

Export Pool Configuration

#!/bin/bash
# export-pool-config.sh

POOL_NAME="Vauly"
OUTPUT_DIR="./pool-export-$(date +%Y%m%d)"

mkdir -p "${OUTPUT_DIR}"

# Pool info
curl -s -X GET "https://192.168.2.150/api/v2.0/pool" \
  -H "Authorization: Bearer ${TRUENAS_API_KEY}" \
  --insecure | jq ".[] | select(.name == \"${POOL_NAME}\")" \
  > "${OUTPUT_DIR}/pool-${POOL_NAME}.json"

# Datasets
curl -s -X GET "https://192.168.2.150/api/v2.0/pool/dataset" \
  -H "Authorization: Bearer ${TRUENAS_API_KEY}" \
  --insecure | jq ".[] | select(.pool == \"${POOL_NAME}\")" \
  > "${OUTPUT_DIR}/datasets-${POOL_NAME}.json"

echo "Pool configuration exported to: ${OUTPUT_DIR}"

Monitor Specific Dataset

#!/bin/bash
# monitor-dataset.sh

DATASET="Vauly/iso-vault"
API_BASE="https://192.168.2.150/api/v2.0"

# URL encode the dataset name
ENCODED_DATASET=$(echo "${DATASET}" | sed 's/\//%2F/g')

curl -s -X GET "${API_BASE}/pool/dataset?id=${ENCODED_DATASET}" \
  -H "Authorization: Bearer ${TRUENAS_API_KEY}" \
  --insecure | jq '{
    name: .name,
    type: .type,
    mountpoint: .mountpoint,
    used: .used.value,
    available: .available.value,
    compression: .compression.value
  }'

Middleware CLI Alternative

For commands requiring higher privileges or unavailable via API:

# Connect via SSH
ssh admin@192.168.2.150

# Use midclt for middleware calls
midclt call system.info
midclt call pool.query
midclt call pool.dataset.query '[["pool", "=", "Vauly"]]'

# Complex queries with filters
midclt call disk.query '[["pool", "=", "Vauly"]]' \
  '{"select": ["name", "serial", "model", "size"]}'

Version Compatibility

This documentation is based on:

  • TrueNAS Scale 23.10.x (Cobia)
  • API version 2.0

Check API version:

curl -X GET "https://192.168.2.150/api/v2.0/system/version" \
  -H "Authorization: Bearer ${TRUENAS_API_KEY}" \
  --insecure

Additional Resources

Official Documentation:

Community:

Tools:

  • API Explorer: https://192.168.2.150/api/docs/ (built-in)

Document Version: 1.0.0 Last Updated: 2025-12-14 API Version: 2.0 Maintained By: Scribe Agent Homelab Repository: /home/jramos/homelab

Reference in New Issue View Git Blame Copy Permalink