dynamicalsystem.com / tinsnip
homelab infrastructure services
fork atom
tinsnip / docs / machine_registry.md
at main 2.7 kB view raw view code
dynamicalsystem.com Rename and update machine registry documentation
8bb4545e

Machine Registry#

The machine registry is a simple key-value mapping that assigns machine numbers to machine names within a sheet.

Location#

The machine registry is stored in the sheet station NFS export:

  • Production: /volume1/{sheet}/station/prod/machines
  • Test: /volume1/{sheet}/station/test/machines

Implementation: The machine registry is automatically created by machine/scripts/setup_station.sh:create_machine_registry() during the machine setup process. This function:

  1. Scans existing system UIDs to discover deployed machines
  2. Creates the registry file with proper ownership (station-prod user)
  3. Populates it with discovered machine mappings

Access Paths:

  • NFS location: /volume1/{sheet}/station/prod/machines
  • Local mount: /mnt/station-prod/data/machines (accessed by lib/uid.sh:calculate_machine_uid())
  • XDG access: ~/.local/share/{sheet}/@station/machines

Format#

The registry uses a simple key=value format, one machine per line:

# Example Machine Registry for a sheet
# Format: machine_name=machine_number
# Machine 0 is reserved for station (sheet infrastructure)

gazette=1
lldap=2
redis=3
prometheus=4
grafana=5

Rules#

  1. Machine 0 is reserved for the sheet station (infrastructure)
  2. Machine names must be lowercase alphanumeric with hyphens allowed
  3. Machine numbers must be unique within a sheet (1-99)
  4. Comments start with # and are ignored
  5. Empty lines are ignored

Usage#

Reading the Registry#

Machines and tools read the registry to determine their machine number:

# Get machine number for 'lldap' in topsheet
machine_num=$(grep "^lldap=" /volume1/topsheet/station/prod/machine-registry | cut -d= -f2)

Adding a New Machine#

  1. Edit the registry file on the NAS
  2. Add a new line with the next available machine number
  3. Ensure no conflicts with existing machines

Example Workflow#

# SSH to NAS
ssh admin@nas.local

# Edit registry for topsheet
sudo vi /volume1/topsheet/station/prod/machine-registry

# Add new machine
echo "caddy=6" >> /volume1/topsheet/station/prod/machine-registry

Integration with tinsnip#

The lib/uid.sh script automatically consults the machine registry when calculating UIDs:

  1. If machine name is "station", use machine number 0
  2. Otherwise, check the registry file
  3. If not found in registry, auto-assign next available number
  4. If still not found, return an error

Future Enhancements#

The station machine (M=0) could eventually provide:

  • REST API for machine registration
  • Web UI for registry management
  • Machine discovery endpoints
  • Port allocation tracking