Rackd Documentation on Rackd

Deployment Guide

Mon, 01 Jan 0001 00:00:00 +0000

This guide covers various deployment methods for Rackd in production environments.

Docker Deployment

Basic Docker Run

# Create data directory
mkdir -p /opt/rackd/data

# Run container
docker run -d \
 --name rackd \
 -p 8080:8080 \
 -v /opt/rackd/data:/data \
 -e DATA_DIR=/data \
 ghcr.io/martinsuchenak/rackd:latest

Docker with Environment Variables

docker run -d \
 --name rackd \
 -p 8080:8080 \
 -v /opt/rackd/data:/data \
 -e DATA_DIR=/data \
 -e LOG_LEVEL=info \
 -e LOG_FORMAT=json \
 -e ENCRYPTION_KEY=your-64-hex-char-key \
 -e INITIAL_ADMIN_USERNAME=admin \
 -e INITIAL_ADMIN_PASSWORD=your-secure-password \
 ghcr.io/martinsuchenak/rackd:latest

Docker Compose

Create docker-compose.yml:

Installation

Mon, 01 Jan 0001 00:00:00 +0000

This guide covers different methods to install and run Rackd.

System Requirements

Minimum Requirements

OS: Linux, macOS, or Windows
RAM: 256 MB
Disk: 100 MB (plus data storage)
CPU: Any modern CPU (x86_64 or ARM64)

Recommended Requirements

RAM: 512 MB or more
Disk: 1 GB or more for data
CPU: 2+ cores for discovery scanning

Installation Methods

1. Download Pre-built Binary (Recommended)

Download the latest release for your platform:

# Linux (x86_64)
curl -LO https://github.com/martinsuchenak/rackd/releases/latest/download/rackd-linux-amd64
chmod +x rackd-linux-amd64
sudo mv rackd-linux-amd64 /usr/local/bin/rackd

# Linux (ARM64)
curl -LO https://github.com/martinsuchenak/rackd/releases/latest/download/rackd-linux-arm64
chmod +x rackd-linux-arm64
sudo mv rackd-linux-arm64 /usr/local/bin/rackd

# macOS (Intel)
curl -LO https://github.com/martinsuchenak/rackd/releases/latest/download/rackd-darwin-amd64
chmod +x rackd-darwin-amd64
sudo mv rackd-darwin-amd64 /usr/local/bin/rackd

# macOS (Apple Silicon)
curl -LO https://github.com/martinsuchenak/rackd/releases/latest/download/rackd-darwin-arm64
chmod +x rackd-darwin-arm64
sudo mv rackd-darwin-arm64 /usr/local/bin/rackd

# Windows (PowerShell)
Invoke-WebRequest -Uri "https://github.com/martinsuchenak/rackd/releases/latest/download/rackd-windows-amd64.exe" -OutFile "rackd.exe"

Verify installation:

IPAM Workflows

Mon, 01 Jan 0001 00:00:00 +0000

IPAM Workflows

Common workflows for IP address management in Rackd.

Initial Network Setup

Create a Network Hierarchy

Start by organizing your IP space:

# Create datacenter
rackd datacenter add --name "Primary DC" --location "US-East"

# Create management network
rackd network add \
 --name "Management Network" \
 --cidr "10.0.0.0/24" \
 --datacenter "Primary DC" \
 --vlan-id 10

# Create production network
rackd network add \
 --name "Production Network" \
 --cidr "10.0.1.0/24" \
 --datacenter "Primary DC" \
 --vlan-id 100

# Create DMZ network
rackd network add \
 --name "DMZ Network" \
 --cidr "10.0.2.0/24" \
 --datacenter "Primary DC" \
 --vlan-id 200

Create IP Pools

Define pools for different purposes:

Managing Devices

Mon, 01 Jan 0001 00:00:00 +0000

Rackd’s device management system provides comprehensive tracking of servers, switches, routers, and other network devices in your infrastructure.

Device Model

A device in Rackd represents any physical or virtual infrastructure component:

type Device struct {
 ID string `json:"id"` // Unique identifier
 Name string `json:"name"` // Device name (required)
 Hostname string `json:"hostname"` // DNS hostname
 Description string `json:"description"` // Device description
 MakeModel string `json:"make_model"` // Manufacturer and model
 OS string `json:"os"` // Operating system
 DatacenterID string `json:"datacenter_id"` // Associated datacenter
 Username string `json:"username"` // Login username
 Location string `json:"location"` // Physical location
 Tags []string `json:"tags"` // Searchable tags
 Addresses []Address `json:"addresses"` // Network addresses
 Domains []string `json:"domains"` // Associated domains
 CreatedAt time.Time `json:"created_at"` // Creation timestamp
 UpdatedAt time.Time `json:"updated_at"` // Last update timestamp
}

Address Model

Each device can have multiple network addresses:

Web UI

Mon, 01 Jan 0001 00:00:00 +0000

The Rackd Web UI provides a modern, responsive interface for managing devices, networks, IP addresses, and datacenter resources. Built with Alpine.js and TailwindCSS, it offers a complete single-page application experience.

UI Overview

The web interface features:

Responsive Design: Works on desktop, tablet, and mobile devices
Dark/Light Theme: Automatic system preference detection with manual toggle
Accessibility: WCAG AAA compliant with keyboard navigation and screen reader support
Real-time Updates: Live data updates without page refreshes
Global Search: Search across devices, networks, and datacenters

The left sidebar provides access to all main sections:

What is Rackd?

Mon, 01 Jan 0001 00:00:00 +0000

Rackd is a lightweight, self-contained IPAM (IP Address Management) and device inventory system built with Go and SQLite. It provides a comprehensive solution for managing your infrastructure with no external dependencies.

Key Features

IP Address Management - Track networks, subnets, and IP allocations with conflict detection
Device Inventory - Manage servers, switches, routers, and network devices
Network Discovery - Automated scanning with multiple protocols
DNS Integration - Sync records with Technitium DNS Server (PowerDNS and BIND planned)
Webhooks & Automation - Event-driven notifications and CI/CD integration
MCP Server - Model Context Protocol for AI tool integration
RBAC Security - Role-based access control with fine-grained permissions

Why Rackd?

Feature	Benefit
Zero Dependencies	Single binary with embedded SQLite - no external database required
CGO-Free	Pure Go compilation for easy cross-platform deployment
Self-Contained	Everything you need in one package
Open Source	MIT licensed and community-driven
Modern UI	Responsive web interface with dark mode support
Full API	REST API for automation and integration

Use Cases

Home Labs - Track your homelab infrastructure and IP allocations
Small Business - Manage office networks and devices
MSPs - Multi-tenant device and network management
DevOps Teams - Infrastructure as code with API integration
Network Engineers - IPAM with automated discovery

Quick Start

# Download the latest release
curl -LO https://github.com/martinsuchenak/rackd/releases/latest/download/rackd-$(uname -s)-$(uname -m)

# Make it executable
chmod +x rackd-*

# Start the server
./rackd-* server

The web interface will be available at http://localhost:8080.

Backup & Restore

Mon, 01 Jan 0001 00:00:00 +0000

This guide covers backup strategies, restore procedures, and data migration for Rackd.

SQLite Backup Strategies

1. File-Based Backup

The simplest approach is copying the SQLite database file:

# Stop Rackd service
systemctl stop rackd

# Copy database file
cp /var/lib/rackd/rackd.db /backup/rackd-$(date +%Y%m%d-%H%M%S).db

# Start Rackd service
systemctl start rackd

2. Online Backup (Recommended)

Use SQLite’s .backup command for consistent backups without stopping the service:

# Create backup while service is running
sqlite3 /var/lib/rackd/rackd.db ".backup /backup/rackd-$(date +%Y%m%d-%H%M%S).db"

3. WAL Mode Backup

If using WAL mode, backup both database and WAL files:

CLI Reference

Mon, 01 Jan 0001 00:00:00 +0000

Complete command-line interface reference for Rackd.

Overview

The Rackd CLI provides full access to all functionality via command-line commands. It communicates with the Rackd server via the REST API.

Global Options

rackd [global options] command [command options] [arguments...]

Global Environment Variables

Variable	Default	Description
`RACKD_SERVER_URL`	`http://localhost:8080`	API server URL
`RACKD_TOKEN`	-	API key used as Bearer token
`RACKD_VERIFY_SSL`	`true`	Set `false`/`0` to skip TLS verification (self-signed certs)
`--help, -h`	-	Show help (all commands)
`--version, -v`	-	Show version

Configuration File

The CLI reads configuration from ~/.config/rackd/config.json (JSON, XDG-aware):

Discovery Examples

Mon, 01 Jan 0001 00:00:00 +0000

Discovery Examples

Examples for using Rackd’s network discovery capabilities.

Basic Discovery

ARP Scan

Discover devices using ARP scanning:

# Scan a network using ARP
rackd discovery scan \
 --network "192.168.1.0/24" \
 --method arp

# View discovered devices
rackd discovery list --status discovered

SNMP Discovery

Discover devices with SNMP:

# Create SNMP credential
rackd credential add \
 --name "snmp-read" \
 --type snmp \
 --community "public" \
 --version 2c

# Run SNMP discovery
rackd discovery scan \
 --network "192.168.1.0/24" \
 --method snmp \
 --credential "snmp-read"

mDNS/Bonjour Discovery

Discover devices advertising via mDNS:

Network Management

Mon, 01 Jan 0001 00:00:00 +0000

Rackd provides comprehensive IP Address Management (IPAM) capabilities for managing networks, subnets, VLANs, IP pools, and tracking IP allocation and utilization across your infrastructure.

Overview

The network management system in Rackd consists of several key components:

Networks: Define network segments with CIDR notation and VLAN assignments
IP Pools: Manage ranges of IP addresses within networks for allocation
IP Allocation: Track which IP addresses are assigned to devices
Utilization Tracking: Monitor IP usage and availability across networks
Heatmaps: Visual representation of IP allocation patterns

Network Model

Networks in Rackd are defined by the following structure (see internal/model/network.go):

Quick Start

Mon, 01 Jan 0001 00:00:00 +0000

Get Rackd running in 5 minutes and perform essential operations.

1. Install and Start (1 minute)

# Download
curl -LO https://github.com/martinsuchenak/rackd/releases/latest/download/rackd-linux-amd64
chmod +x rackd-linux-amd64

# Bootstrap the first admin and start the server
export INITIAL_ADMIN_USERNAME=admin
export INITIAL_ADMIN_PASSWORD=your-secure-password
./rackd-linux-amd64 server

Open http://localhost:8080 and sign in with the admin credentials you set above — authentication is required for everything (the CLI too). For CLI convenience, create an API key in the web UI (Settings → API Keys) and export it:

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Rackd can be configured through environment variables. All configuration options have sensible defaults and can be overridden as needed.

Environment Variables

Server Options

Variable	Default	Description
`DATA_DIR`	`./data`	Directory for SQLite database and application data
`LISTEN_ADDR`	`:8080`	Address and port for the HTTP server (e.g., `:8080`, `127.0.0.1:3000`)

Security Options

Variable	Default	Description
`ENCRYPTION_KEY`	(empty)	64 hex chars (32 bytes). Encrypts stored SNMP/SSH credentials, DNS provider tokens and webhook secrets at rest. Generate with `openssl rand -hex 32`. Without it (outside `--dev-mode`) credential/DNS features are disabled
`INITIAL_ADMIN_USERNAME`	(empty)	Bootstrap admin username, applied only when the database has no users
`INITIAL_ADMIN_PASSWORD`	(empty)	Bootstrap admin password (min 8 characters)
`INITIAL_ADMIN_EMAIL`	`admin@localhost`	Bootstrap admin email
`COOKIE_SECURE`	`true`	Send session cookies only over HTTPS. Set to `false` for local dev without TLS
`SESSION_TTL`	`24h`	Duration for which a user session is valid
`SESSION_STORE_TYPE`	`sqlite`	The backend storage for sessions (`sqlite`, `valkey`, `redis`)
`VALKEY_URL`	`redis://localhost:6379/0`	The URL for Valkey/Redis if `SESSION_STORE_TYPE` is `valkey` or `redis`
`TRUST_PROXY`	`false`	Honor `X-Forwarded-For` / `X-Real-IP` headers from reverse proxies (rate limiting, audit logging)
`TRUSTED_PROXIES`	(empty)	Comma-separated IPs/CIDRs of trusted reverse proxies. Required when `TRUST_PROXY=true`: forwarded headers are honored only from these peers, otherwise ignored (fail-closed)
`SSRF_ALLOW_PRIVATE_TARGETS`	`false`	Allow webhook and DNS provider endpoints on private ranges (RFC1918/CGNAT/ULA) for intentional internal integrations. Loopback, link-local (cloud metadata) and multicast are always blocked

Rate Limiting Options

Variable	Default	Description
`RATE_LIMIT_ENABLED`	`true`	Enable API rate limiting. Set to `false` to disable for local dev
`RATE_LIMIT_REQUESTS`	`100`	Maximum requests per window
`RATE_LIMIT_WINDOW`	`1m`	Time window for rate limiting (Go duration format)

See Rate Limiting for detailed documentation.

Datacenters

Mon, 01 Jan 0001 00:00:00 +0000

Rackd’s datacenter management system provides organization and tracking of physical locations where your infrastructure is deployed.

Datacenter Model

A datacenter in Rackd represents a physical location containing infrastructure devices:

type Datacenter struct {
 ID string `json:"id"` // Unique identifier
 Name string `json:"name"` // Datacenter name (required)
 Location string `json:"location"` // Geographic location
 Description string `json:"description"` // Datacenter description
 CreatedAt time.Time `json:"created_at"` // Creation timestamp
 UpdatedAt time.Time `json:"updated_at"` // Last update timestamp
}

Validation Rules

Name: Required, maximum 255 characters
Location: Optional, maximum 255 characters
Description: Optional, maximum 4096 characters

CRUD Operations

Create Datacenter

CLI:

REST API

Mon, 01 Jan 0001 00:00:00 +0000

The Rackd REST API provides programmatic access to all infrastructure management features including devices, networks, datacenters, IP pools, discovery, and relationships.

Base URL

http://localhost:8080/api

Authentication

Authentication is required on all API endpoints. Rackd accepts:

Session cookie - set by POST /api/auth/login (HttpOnly, SameSite=Strict)
API key - Bearer token created in the web UI or via rackd apikey generate

Authorization: Bearer <your-api-key>

GET /healthz, GET /readyz, the login endpoint and the OAuth discovery endpoints are the only unauthenticated routes.

Sample Scripts

Mon, 01 Jan 0001 00:00:00 +0000

Sample Scripts

Collection of sample scripts for automating Rackd operations.

Python SDK

Installation

pip install rackd-sdk

Basic Usage

from rackd import Client

# Initialize client
client = Client(
 host="https://rackd.example.com",
 api_key="your-api-key"
)

# List devices
devices = client.devices.list()
for device in devices:
 print(f"{device.hostname}: {device.primary_ip}")

# Create a device
device = client.devices.create(
 hostname="new-server-01",
 datacenter="Primary DC",
 ip_addresses=[{"address": "192.168.1.10", "primary": True}],
 status="planned"
)

# Update device
device.update(status="active")

# Delete device
device.delete()

IP Allocation

from rackd import Client

client = Client(host="https://rackd.example.com", api_key="your-api-key")

# Get next available IP
network = client.networks.get("Production Network")
next_ip = network.allocate_ip()

print(f"Allocated IP: {next_ip.address}")

# Create device with allocated IP
device = client.devices.create(
 hostname=f"server-{next_ip.address.split('.')[-1]}",
 ip_addresses=[{"address": next_ip.address, "primary": True}],
 datacenter="Primary DC"
)

Bash Scripts

Health Check Script

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

RACKD_HOST="https://rackd.example.com"
API_KEY="your-api-key"

check_health() {
 response=$(curl -s -o /dev/null -w "%{http_code}" \
 -H "X-API-Key: $API_KEY" \
 "$RACKD_HOST/healthz")

 if [ "$response" -eq 200 ]; then
 echo "OK: Rackd is healthy"
 return 0
 else
 echo "CRITICAL: Rackd returned $response"
 return 2
 fi
}

check_device_count() {
 count=$(curl -s -H "X-API-Key: $API_KEY" \
 "$RACKD_HOST/api/devices?limit=0" | \
 jq -r '.total')

 echo "INFO: $count devices in inventory"
}

check_utilization() {
 utilization=$(curl -s -H "X-API-Key: $API_KEY" \
 "$RACKD_HOST/api/networks/Production%20Network" | \
 jq -r '.utilization')

 echo "INFO: Production network utilization: ${utilization}%"

 if (( $(echo "$utilization > 90" | bc -l) )); then
 echo "WARNING: Network utilization above 90%"
 return 1
 fi
}

# Run checks
check_health
check_device_count
check_utilization

Backup Script

#!/bin/bash
# backup-rackd.sh

RACKD_HOST="https://rackd.example.com"
API_KEY="your-api-key"
BACKUP_DIR="/backups/rackd"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p "$BACKUP_DIR"

# Export all data
curl -s -H "X-API-Key: $API_KEY" \
 "$RACKD_HOST/api/export?format=json" \
 -o "$BACKUP_DIR/rackd-backup-$DATE.json"

# Compress
gzip "$BACKUP_DIR/rackd-backup-$DATE.json"

# Keep only last 30 days
find "$BACKUP_DIR" -name "*.gz" -mtime +30 -delete

echo "Backup completed: rackd-backup-$DATE.json.gz"

Device Provisioning

#!/bin/bash
# provision-device.sh

RACKD_HOST="https://rackd.example.com"
API_KEY="your-api-key"

provision_device() {
 local hostname=$1
 local network=$2
 local datacenter=$3

 # Get next IP
 ip=$(curl -s -X POST \
 -H "X-API-Key: $API_KEY" \
 "$RACKD_HOST/api/networks/$network/next-ip" | \
 jq -r '.address')

 # Create device
 device_id=$(curl -s -X POST \
 -H "X-API-Key: $API_KEY" \
 -H "Content-Type: application/json" \
 -d "{
 \"hostname\": \"$hostname\",
 \"datacenter\": \"$datacenter\",
 \"ip_addresses\": [{\"address\": \"$ip\", \"primary\": true}],
 \"status\": \"planned\"
 }" \
 "$RACKD_HOST/api/devices" | jq -r '.id')

 echo "Provisioned: $hostname ($ip) - ID: $device_id"
}

# Provision multiple devices
for i in {1..5}; do
 provision_device "web-server-$i" "Production Network" "Primary DC"
done

PowerShell Scripts

Basic Operations

# rackd-client.ps1

$RackdHost = "https://rackd.example.com"
$ApiKey = "your-api-key"
$Headers = @{
 "X-API-Key" = $ApiKey
}

function Get-Devices {
 $response = Invoke-RestMethod -Uri "$RackdHost/api/devices" -Headers $Headers
 return $response
}

function Get-Device {
 param($Hostname)
 $response = Invoke-RestMethod -Uri "$RackdHost/api/devices?hostname=$Hostname" -Headers $Headers
 return $response[0]
}

function New-Device {
 param(
 $Hostname,
 $IPAddress,
 $Datacenter,
 $Status = "planned"
 )

 $body = @{
 hostname = $Hostname
 datacenter = $Datacenter
 ip_addresses = @(
 @{
 address = $IPAddress
 primary = $true
 }
 )
 status = $Status
 } | ConvertTo-Json -Depth 3

 $response = Invoke-RestMethod -Uri "$RackdHost/api/devices" `
 -Method POST `
 -Headers $Headers `
 -ContentType "application/json" `
 -Body $body

 return $response
}

# Usage examples
$devices = Get-Devices
$devices | ForEach-Object { Write-Host "$($_.hostname): $($_.primary_ip)" }

Go Examples

Basic Client

package main

import (
 "context"
 "fmt"
 "log"

 "github.com/martinsuchenak/rackd-go"
)

func main() {
 client, err := rackd.NewClient("https://rackd.example.com", "your-api-key")
 if err != nil {
 log.Fatal(err)
 }

 // List devices
 devices, err := client.Devices.List(context.Background())
 if err != nil {
 log.Fatal(err)
 }

 for _, device := range devices {
 fmt.Printf("%s: %s\n", device.Hostname, device.PrimaryIP)
 }
}

Best Practices

Error Handling

import requests
from requests.exceptions import RequestException

def safe_api_call(func):
 def wrapper(*args, **kwargs):
 try:
 return func(*args, **kwargs)
 except RequestException as e:
 print(f"API Error: {e}")
 return None
 except Exception as e:
 print(f"Unexpected error: {e}")
 return None
 return wrapper

@safe_api_call
def get_devices(client):
 return client.devices.list()

Rate Limiting

import time
from functools import wraps

def rate_limit(calls_per_second):
 min_interval = 1.0 / calls_per_second
 def decorator(func):
 last_called = [0.0]
 @wraps(func)
 def wrapper(*args, **kwargs):
 elapsed = time.time() - last_called[0]
 if elapsed < min_interval:
 time.sleep(min_interval - elapsed)
 result = func(*args, **kwargs)
 last_called[0] = time.time()
 return result
 return wrapper
 return decorator

@rate_limit(10) # 10 calls per second
def api_call(client, endpoint):
 return requests.get(f"{client.host}{endpoint}", headers=client.headers)

Security Hardening

Mon, 01 Jan 0001 00:00:00 +0000

Security considerations and hardening guide for production Rackd deployments.

Authentication

Rackd requires authentication on all API endpoints. Three methods are supported:

Session cookies (Web UI login)
API keys (Bearer token, tied to a user account)
OAuth 2.1 with PKCE (MCP clients)

See Authentication for details on each method.

Secure Defaults

Rackd ships with secure defaults for production use:

Setting	Default	Description
`COOKIE_SECURE`	`true`	Session cookies only sent over HTTPS
`RATE_LIMIT_ENABLED`	`true`	API rate limiting active
`RATE_LIMIT_REQUESTS`	`100`	100 requests per minute per IP
`LOGIN_RATE_LIMIT_REQUESTS`	`5`	5 login attempts per minute per IP

For local development without TLS, use --dev-mode which disables COOKIE_SECURE and RATE_LIMIT_ENABLED automatically.

Configuration Reference

Mon, 01 Jan 0001 00:00:00 +0000

All configuration is done via environment variables. Variables can be set directly or loaded from a .env file in the working directory.

Use --dev-mode flag on rackd server to automatically disable COOKIE_SECURE and RATE_LIMIT_ENABLED for local development.

Server

Variable	Type	Default	Description
`DATA_DIR`	string	`./data`	Directory for SQLite database and data files
`LISTEN_ADDR`	string	`:8080`	Address and port to listen on
`REQUEST_TIMEOUT`	duration	`30s`	HTTP request timeout
`LOG_FORMAT`	string	`text`	Log format: `text` or `json`
`LOG_LEVEL`	string	`info`	Log level: `trace`, `debug`, `info`, `warn`, `error`

Security

Variable	Type	Default	Description
`ENCRYPTION_KEY`	string	(empty)	64 hex chars (32 bytes). Encrypts stored SNMP/SSH credentials, DNS provider tokens and webhook signing secrets at rest. Generate with `openssl rand -hex 32`. Without it (outside `--dev-mode`) the credentials/DNS features are disabled; with `--dev-mode` a random non-persistent key is used. Rotate with `rackd credentials rotate-key`
`COOKIE_SECURE`	bool	`true`	Set `Secure` flag on session cookies (requires HTTPS). Disable for local dev without TLS
`RATE_LIMIT_ENABLED`	bool	`true`	Enable API rate limiting
`RATE_LIMIT_REQUESTS`	int	`100`	Max requests per window per IP
`RATE_LIMIT_WINDOW`	duration	`1m`	Rate limit sliding window
`LOGIN_RATE_LIMIT_REQUESTS`	int	`5`	Max login attempts per window per IP
`LOGIN_RATE_LIMIT_WINDOW`	duration	`1m`	Login rate limit sliding window
`TRUST_PROXY`	bool	`false`	Honor `X-Forwarded-For` / `X-Real-IP` headers when determining the client IP (rate limiting, audit logging)
`TRUSTED_PROXIES`	string	(empty)	Comma-separated IPs/CIDRs of trusted reverse proxies (e.g. `127.0.0.1,10.0.0.0/8`). Required when `TRUST_PROXY=true`: forwarded headers are honored only when the direct peer matches one of these networks, otherwise ignored (fail-closed)
`SSRF_ALLOW_PRIVATE_TARGETS`	bool	`false`	Permit webhook and DNS provider endpoints on private ranges (RFC1918/CGNAT/ULA) for intentional internal integrations. Loopback, link-local (cloud metadata) and multicast targets are always blocked

Sessions

Variable	Type	Default	Description
`SESSION_TTL`	duration	`24h`	Session expiry after last activity
`SESSION_STORE_TYPE`	string	`sqlite`	Session store backend: `sqlite` or `valkey`
`VALKEY_URL`	string	`redis://localhost:6379/0`	Valkey/Redis URL (when `SESSION_STORE_TYPE=valkey`)

Initial Admin

These are only used on first startup when no users exist.

Discovery & Scanning

Mon, 01 Jan 0001 00:00:00 +0000

Rackd’s discovery system provides automated network scanning and device detection capabilities. It can discover devices across networks using multiple scanning techniques including basic port scanning, SSH, and SNMP.

Overview

The discovery system consists of:

Network Scanning: Automated discovery of devices on networks
Scan Types: Basic, advanced, and custom scanning profiles
Credentials Management: Secure storage of SSH and SNMP credentials
Scheduled Scans: Automated recurring discovery
Device Promotion: Converting discovered devices to managed inventory

Scan Types

Basic Scan Types

Quick Scan

Purpose: Fast network discovery for basic connectivity
Method: TCP port scanning on common ports (22, 80, 443, 3389)
Speed: Fastest option
Use Case: Initial network discovery, connectivity checks

Full Scan

Purpose: Comprehensive port scanning
Method: Scans top 100 most common ports
Speed: Moderate
Use Case: Detailed service discovery

Deep Scan

Purpose: Extensive network analysis
Method: Extended port range scanning with service detection
Speed: Slowest but most thorough
Use Case: Security audits, complete network mapping

Advanced Scanning

Advanced scans use scan profiles with customizable parameters:

MCP Server

Mon, 01 Jan 0001 00:00:00 +0000

The Rackd MCP (Model Context Protocol) server provides AI tools and automation systems with direct access to device inventory, network management, and datacenter operations through a standardized protocol.

Overview

MCP is an open protocol that enables AI assistants and automation tools to interact with external systems through a standardized interface. Rackd’s MCP server exposes all core functionality as tools that can be called by MCP clients like Claude Desktop, custom automation scripts, or other AI systems.

Monitoring

Mon, 01 Jan 0001 00:00:00 +0000

Rackd provides comprehensive monitoring capabilities through Prometheus-compatible metrics, health checks, and structured logging.

Health Checks

Rackd exposes two health check endpoints for container orchestration and load balancers:

Liveness Probe (`/healthz`)

Simple endpoint that returns 200 OK if the application is running.

curl http://localhost:8080/healthz
# Response: ok

Use case: Kubernetes liveness probe to detect if the application needs to be restarted.

livenessProbe:
 httpGet:
 path: /healthz
 port: 8080
 initialDelaySeconds: 10
 periodSeconds: 30

Readiness Probe (`/readyz`)

Detailed endpoint that checks if the application is ready to serve traffic.

Authentication

Mon, 01 Jan 0001 00:00:00 +0000

Rackd supports multiple authentication methods: user sessions (Web UI), API keys (REST API and MCP), and OAuth 2.1 with PKCE (MCP).

Overview

All API endpoints require authentication. There is no anonymous access mode. On first startup, create an admin user via environment variables (see Configuration Reference) or the bootstrap flow.

Authentication Methods

1. Session Authentication (Web UI)

The Web UI uses session-based authentication with secure cookies.

POST /api/auth/login
Content-Type: application/json

{"username": "admin", "password": "your-password"}

Session properties:

Device Relationships

Mon, 01 Jan 0001 00:00:00 +0000

Rackd supports tracking relationships between devices to model physical connections, dependencies, and containment hierarchies in your infrastructure.

Relationship Types

contains

Represents physical or logical containment relationships.

Examples:

Rack contains servers
Chassis contains blade servers
Switch contains line cards
Datacenter contains racks

connected_to

Represents physical network or power connections between devices.

Examples:

Server connected to switch via network cable
Switch connected to router
Server connected to PDU for power
Storage array connected to SAN switch

depends_on

Represents logical dependencies where one device relies on another for functionality.

Rate Limiting

Mon, 01 Jan 0001 00:00:00 +0000

Rackd includes built-in rate limiting to prevent API abuse and ensure fair resource usage across clients.

Overview

Rate limiting is enabled by default (RATE_LIMIT_ENABLED=true). It tracks request rates per client IP and returns HTTP 429 (Too Many Requests) when limits are exceeded. Disable it with RATE_LIMIT_ENABLED=false for local development.

Configuration

Rate limiting is configured via environment variables:

# Rate limiting (enabled by default)
RATE_LIMIT_ENABLED=true

# Maximum requests per window (default: 100)
RATE_LIMIT_REQUESTS=100

# Time window for rate limiting (default: 1m)
RATE_LIMIT_WINDOW=1m

Example Configurations

Strict limits for public API:

Audit Logging

Mon, 01 Jan 0001 00:00:00 +0000

Rackd includes comprehensive audit logging to track all changes for compliance, security, and troubleshooting.

Overview

The audit trail captures all mutating API operations with full context including user, IP address, resource details, and changes. This provides accountability, compliance support, and troubleshooting capabilities.

Key Features:

Automatic capture of all API changes
User and IP address tracking
Request body capture for change details
Flexible filtering and querying
Export to JSON/CSV
Automatic retention management
Disabled by default (opt-in)

Configuration

Audit logging is configured via environment variables:

Device Lifecycle

Mon, 01 Jan 0001 00:00:00 +0000

Rackd tracks device lifecycle states to help manage infrastructure from planning through decommissioning.

Overview

Device lifecycle tracking provides:

Clear visibility into device status
Historical tracking of status changes
Scheduled decommission planning
Status-based filtering and reporting
Dashboard summaries by status

Device Status

Status	Description
`planned`	Device is planned but not yet deployed
`active`	Device is operational
`maintenance`	Device is under maintenance
`decommissioned`	Device has been retired

Status Model

The device model includes status-related fields:

User Authentication

Mon, 01 Jan 0001 00:00:00 +0000

Rackd supports user authentication via environment variable bootstrapping and password-based login.

Initial Admin User

On first startup, Rackd can create an initial admin user if you provide credentials via environment variables. This follows industry standards for containerized deployments.

Environment Variables

# Required
INITIAL_ADMIN_USERNAME=admin # Username for initial admin
INITIAL_ADMIN_PASSWORD=securepass # Password (min 8 characters)

# Optional
INITIAL_ADMIN_EMAIL=admin@example.com # Email (default: admin@localhost)
INITIAL_ADMIN_FULL_NAME="Admin User" # Full name (default: System Administrator)
SESSION_TTL=24h # Session timeout (default: 24h)
SESSION_STORE_TYPE=sqlite # Session store backend (sqlite, valkey)
VALKEY_URL=redis://localhost:6379/0 # Valkey/Redis URL if used

Docker Example

docker run -d \
 -e INITIAL_ADMIN_USERNAME=admin \
 -e INITIAL_ADMIN_PASSWORD=mySecurePassword123 \
 -e INITIAL_ADMIN_EMAIL=admin@example.com \
 -p 8080:8080 \
 rackd

Kubernetes Example

apiVersion: v1
kind: Secret
metadata:
 name: rackd-admin
type: Opaque
stringData:
 username: admin
 password: mySecurePassword123
---
apiVersion: v1
kind: Pod
metadata:
 name: rackd
spec:
 containers:
 - name: rackd
 image: rackd:latest
 env:
 - name: INITIAL_ADMIN_USERNAME
 valueFrom:
 secretKeyRef:
 name: rackd-admin
 key: username
 - name: INITIAL_ADMIN_PASSWORD
 valueFrom:
 secretKeyRef:
 name: rackd-admin
 key: password

Session Management

Session Tokens

After login, users receive a session token that must be included in the Authorization header:

IP Reservations

Mon, 01 Jan 0001 00:00:00 +0000

Rackd provides IP reservation functionality for planning and managing IP address allocations before devices are provisioned.

Overview

IP reservations allow you to:

Reserve IPs for future use
Plan IP allocations during infrastructure planning
Prevent accidental IP conflicts
Track reservation purposes and owners
Auto-expire unused reservations

Reservation Model

Field	Type	Description
`id`	string	Unique identifier
`pool_id`	string	Parent IP pool
`ip_address`	string	Reserved IP address
`purpose`	string	Reason for reservation
`reserved_by`	string	User who made the reservation
`device_id`	string	Optional linked device
`status`	string	Reservation status
`expires_at`	timestamp	Expiration date (optional)
`created_at`	timestamp	Creation timestamp
`updated_at`	timestamp	Last update timestamp

Reservation Status

Status	Description
`active`	Reservation is currently active
`expired`	Reservation has passed expiration date
`claimed`	IP has been assigned to a device
`released`	Reservation was manually released

API Endpoints

List Reservations

GET /api/pools/{pool_id}/reservations

Query parameters:

Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

Common issues and solutions for Rackd.

Server Issues

Server Won’t Start

Port Already in Use

Symptom:

Error: listen tcp :8080: bind: address already in use

Solution:

# Find what's using the port
sudo lsof -i :8080
# or
sudo netstat -tulpn | grep :8080

# Kill the process
sudo kill <PID>

# Or use a different port
rackd server --listen-addr :8081

Permission Denied

Symptom:

Error: open /var/lib/rackd/rackd.db: permission denied

Solution:

Conflict Detection

Mon, 01 Jan 0001 00:00:00 +0000

Rackd automatically detects and tracks IP address conflicts to help maintain network integrity.

Overview

IP conflicts occur when:

Multiple devices are assigned the same IP address
Network subnets overlap
Reserved IPs are assigned to devices

Rackd detects these conflicts automatically and provides tools for resolution.

Conflict Types

Type	Description
`duplicate_ip`	Same IP assigned to multiple devices
`overlapping_subnet`	Network subnets overlap
`reserved_ip_assigned`	Reserved IP assigned to a device

Conflict Status

Status	Description
`active`	Conflict currently exists
`resolved`	Conflict has been resolved
`ignored`	Conflict marked as acceptable

Conflict Model

Field	Type	Description
`id`	string	Unique identifier
`type`	string	Conflict type
`status`	string	Current status
`ip_address`	string	Affected IP address (for duplicate_ip)
`network_id`	string	Affected network (for overlapping_subnet)
`device_ids`	[]string	IDs of conflicting devices
`description`	string	Human-readable description
`resolution`	string	How the conflict was resolved
`resolved_at`	timestamp	When conflict was resolved
`resolved_by`	string	User who resolved the conflict
`created_at`	timestamp	When conflict was detected
`updated_at`	timestamp	Last update timestamp

Automatic Detection

Conflicts are automatically detected when:

DNS Integration

Mon, 01 Jan 0001 00:00:00 +0000

Rackd provides DNS integration with external DNS servers, allowing automatic management of DNS records for devices in your inventory.

Overview

The DNS integration enables:

Automatic A/AAAA record creation for devices
Automatic PTR record generation for reverse DNS lookups
Integration with multiple DNS provider types
Bidirectional sync between Rackd and DNS servers

Supported Providers

Provider	Type	Status
Technitium	`technitium`	✅ Available
PowerDNS	`powerdns`	🚧 Coming Soon
BIND	`bind`	🚧 Coming Soon

Configuration

Environment Variables

DNS_SYNC_INTERVAL=1h # Interval between automatic sync operations

DNS_SYNC_INTERVAL

Controls how often Rackd automatically syncs DNS zones that have auto_sync enabled.

Webhooks & Events

Mon, 01 Jan 0001 00:00:00 +0000

Rackd provides a webhook system for event-driven automation and external integrations.

Overview

Webhooks allow external systems to receive real-time notifications when events occur in Rackd. This enables:

Automated workflows triggered by device changes
Integration with monitoring and ticketing systems
Real-time sync with CMDBs and asset management tools
Custom alerting and notification pipelines

Webhook Model

Field	Type	Description
`id`	string	Unique identifier
`name`	string	Descriptive name
`url`	string	Target URL for webhook delivery
`secret`	string	Secret for HMAC signature (write-only)
`events`	[]string	List of subscribed events
`enabled`	bool	Whether webhook is active
`description`	string	Optional description
`headers`	map	Custom HTTP headers
`timeout_seconds`	int	Request timeout (default: 10)
`retry_count`	int	Number of retries on failure (default: 3)
`created_at`	timestamp	Creation timestamp
`updated_at`	timestamp	Last update timestamp

Supported Events

Device Events

Event	Description
`device.created`	New device added
`device.updated`	Device properties changed
`device.deleted`	Device removed
`device.promoted`	Device promoted from discovered

Network Events

Event	Description
`network.created`	New network created
`network.updated`	Network properties changed
`network.deleted`	Network removed

Discovery Events

Event	Description
`discovery.started`	Discovery scan started
`discovery.completed`	Discovery scan completed
`discovery.device_found`	New device discovered

Conflict Events

Event	Description
`conflict.detected`	IP conflict detected
`conflict.resolved`	Conflict resolved

Pool Events

Event	Description
`pool.utilization_high`	Pool utilization exceeds threshold

Webhook Delivery

Request Format

Webhooks are delivered as HTTP POST requests with JSON payloads:

Custom Fields

Mon, 01 Jan 0001 00:00:00 +0000

Rackd supports user-defined custom fields for devices, allowing you to track additional metadata specific to your organization.

Overview

Custom fields provide flexibility to extend device records with organization-specific data:

Asset tracking numbers
Warranty information
Department/owner assignments
Physical location details
Compliance attributes
Any custom metadata you need

Custom Field Types

Type	Description	Example
`text`	Free-form text input	Serial numbers, notes
`number`	Numeric values	Rack units, power draw
`boolean`	True/false checkbox	Under maintenance
`select`	Dropdown with predefined options	Environment, tier

Custom Field Definition

Field	Type	Description
`id`	string	Unique identifier
`name`	string	Field name (display label)
`key`	string	Unique key for API access
`type`	string	Field type (text/number/boolean/select)
`required`	bool	Whether field is mandatory
`description`	string	Help text for users
`options`	[]string	Options for select type
`default_value`	string	Default value for new devices
`sort_order`	int	Display order
`created_at`	timestamp	Creation timestamp
`updated_at`	timestamp	Last update timestamp

API Endpoints

List Custom Field Definitions

GET /api/custom-fields

Response:

Circuit Tracking

Mon, 01 Jan 0001 00:00:00 +0000

Rackd provides circuit tracking for managing network circuits including fiber, copper, microwave, and dark fiber connections.

Overview

Circuit management allows you to:

Track circuit provider information and circuit IDs
Monitor circuit status and capacity
Link circuits to devices and datacenters
Maintain circuit documentation and history
Plan circuit decommissioning

Circuit Model

Field	Type	Description
`id`	string	Unique identifier (auto-generated UUID)
`name`	string	Descriptive name for the circuit
`provider`	string	Circuit provider name (e.g., “AT&T”, “Lumen”)
`circuit_id`	string	Provider’s circuit identifier
`type`	string	Circuit type: `fiber`, `copper`, `microwave`, `dark_fiber`
`status`	string	Status: `active`, `inactive`, `planned`, `decommissioned`
`capacity_mbps`	int	Circuit capacity in Mbps
`a_endpoint`	string	A-side endpoint location/device
`z_endpoint`	string	Z-side endpoint location/device
`datacenter_id`	string	Optional associated datacenter
`device_id`	string	Optional linked device
`description`	string	Optional description
`tags`	[]string	Optional tags for categorization
`install_date`	date	Installation date
`termination_date`	date	Contract termination date
`created_at`	timestamp	Creation timestamp
`updated_at`	timestamp	Last update timestamp

Circuit Types

Type	Description
`fiber`	Active fiber optic circuit
`copper`	Copper-based circuit (T1, DS3, etc.)
`microwave`	Wireless microwave link
`dark_fiber`	Unlit fiber (point-to-point)

Circuit Status

Status	Description
`active`	Circuit is operational
`inactive`	Circuit is temporarily down
`planned`	Circuit is planned but not yet installed
`decommissioned`	Circuit has been retired

API Endpoints

List Circuits

GET /api/circuits

Query parameters:

NAT Management

Mon, 01 Jan 0001 00:00:00 +0000

Rackd provides comprehensive NAT (Network Address Translation) mapping management for tracking external-to-internal IP/port translations.

Overview

NAT tracking allows you to document and manage NAT mappings in your network infrastructure. This is essential for:

Documenting firewall rules and port forwards
Tracking which external IPs map to internal services
Managing IP address utilization across NAT boundaries
Audit trail for NAT configuration changes

NAT Mapping Model

Each NAT mapping contains:

Field	Type	Description
`id`	string	Unique identifier (auto-generated UUID)
`name`	string	Descriptive name for the mapping
`external_ip`	string	External/public IP address
`external_port`	int	External port number (1-65535)
`internal_ip`	string	Internal/private IP address
`internal_port`	int	Internal port number (1-65535)
`protocol`	string	Protocol: `tcp`, `udp`, or `any` (default: `tcp`)
`device_id`	string	Optional linked device ID
`datacenter_id`	string	Optional datacenter ID
`network_id`	string	Optional network ID
`description`	string	Optional description
`enabled`	bool	Whether the mapping is active (default: `true`)
`tags`	[]string	Optional tags for categorization
`created_at`	timestamp	Creation timestamp
`updated_at`	timestamp	Last update timestamp

API Endpoints

List NAT Mappings

GET /api/nat

Query parameters:

Dashboard & Analytics

Mon, 01 Jan 0001 00:00:00 +0000

Rackd provides an enhanced dashboard with utilization trends, activity feeds, and aggregated statistics.

Overview

The dashboard provides at-a-glance visibility into:

Overall infrastructure health
Pool utilization trends
Network utilization summary
Recent device discoveries
Stale device detection
Conflict alerts

Dashboard API

Get Dashboard Stats

GET /api/dashboard

Response:

{
 "total_devices": 500,
 "total_networks": 25,
 "total_pools": 40,
 "active_conflicts": 3,
 "devices_by_status": {
 "planned": 10,
 "active": 475,
 "maintenance": 5,
 "decommissioned": 10
 },
 "recent_discoveries": [
 {
 "hostname": "new-server-01",
 "ip_address": "192.168.1.100",
 "discovered_at": "2024-02-27T09:30:00Z"
 }
 ],
 "network_utilization": [
 {
 "network_id": "net-1",
 "network_name": "Production LAN",
 "cidr": "192.168.1.0/24",
 "utilization_percent": 75.5
 }
 ],
 "stale_devices": 12,
 "health_alerts": [
 {
 "type": "high_utilization",
 "resource": "Production Pool",
 "value": 92,
 "threshold": 90
 }
 ]
}

Get Utilization Trend

GET /api/dashboard/trend

Query parameters:

Role-Based Access Control

Mon, 01 Jan 0001 00:00:00 +0000

Rackd implements role-based access control (RBAC) for fine-grained permission management.

Overview

RBAC in Rackd follows the standard model:

Users - Accounts that can authenticate
Roles - Collections of permissions
Permissions - Fine-grained resource:action access controls

Users are assigned roles, and roles grant permissions. A user’s effective permissions are the union of all permissions from their assigned roles.

Default Roles

Rackd includes three built-in system roles that cannot be modified or deleted:

Full-Text Search

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Rackd includes SQLite FTS5 (Full-Text Search) for fast, efficient searching across devices, networks, and datacenters via a unified search API.

Features

Unified search endpoint - Single /api/search endpoint returns all matching results
FTS5-powered search for devices, networks, and datacenters
Comprehensive device search across:
- Device fields (name, hostname, description, make/model, OS, location)
- Tags
- Domains
- IP addresses
Network search across name, subnet, and description
Datacenter search across name, location, and description
Automatic index maintenance via SQLite triggers
Special character handling for safe query execution

API Endpoint

Unified Search

GET /api/search?q=<query>

Returns:

Changelog

Mon, 01 Jan 0001 00:00:00 +0000

Release notes for each version of Rackd. Downloads are on the GitHub releases page.

Rackd Documentation on Rackd

Deployment Guide

Docker Deployment

Basic Docker Run

Docker with Environment Variables

Docker Compose

Installation

System Requirements

Minimum Requirements

Recommended Requirements

Installation Methods

1. Download Pre-built Binary (Recommended)

IPAM Workflows

IPAM Workflows

Initial Network Setup

Create a Network Hierarchy

Create IP Pools

Managing Devices

Device Model

Address Model

Web UI

UI Overview

Navigation

Sidebar Navigation

What is Rackd?

Key Features

Why Rackd?

Use Cases

Quick Start

Backup & Restore

SQLite Backup Strategies

1. File-Based Backup

2. Online Backup (Recommended)

3. WAL Mode Backup

CLI Reference

Overview

Global Options

Global Environment Variables

Configuration File

Discovery Examples

Discovery Examples

Basic Discovery

ARP Scan

SNMP Discovery

mDNS/Bonjour Discovery

Network Management

Overview

Network Model

Quick Start

1. Install and Start (1 minute)

Configuration

Environment Variables

Server Options

Security Options

Rate Limiting Options

Datacenters

Datacenter Model

Validation Rules

CRUD Operations

Create Datacenter

REST API

Base URL

Authentication

Sample Scripts

Sample Scripts

Python SDK

Installation

Basic Usage

IP Allocation

Bash Scripts

Health Check Script

Backup Script

Device Provisioning

PowerShell Scripts

Basic Operations

Go Examples

Basic Client

Best Practices

Error Handling

Rate Limiting

Liveness Probe (`/healthz`)

Readiness Probe (`/readyz`)