User Guides on Rackd

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:

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):

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:

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:

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.

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:

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:

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: