dynamicalsystem.com
homelab infrastructure services
1# Machine Registry
2
3The machine registry is a simple key-value mapping that assigns machine numbers to machine names within a sheet.
4
5## Location
6
7The machine registry is stored in the sheet station NFS export:
8- Production: `/volume1/{sheet}/station/prod/machines`
9- Test: `/volume1/{sheet}/station/test/machines`
10
11**Implementation:** The machine registry is automatically created by `machine/scripts/setup_station.sh:create_machine_registry()` during the machine setup process. This function:
121. Scans existing system UIDs to discover deployed machines
132. Creates the registry file with proper ownership (station-prod user)
143. Populates it with discovered machine mappings
15
16**Access Paths:**
17- NFS location: `/volume1/{sheet}/station/prod/machines`
18- Local mount: `/mnt/station-prod/data/machines` (accessed by `lib/uid.sh:calculate_machine_uid()`)
19- XDG access: `~/.local/share/{sheet}/@station/machines`
20
21## Format
22
23The registry uses a simple `key=value` format, one machine per line:
24
25```
26# Example Machine Registry for a sheet
27# Format: machine_name=machine_number
28# Machine 0 is reserved for station (sheet infrastructure)
29
30gazette=1
31lldap=2
32redis=3
33prometheus=4
34grafana=5
35```
36
37## Rules
38
391. **Machine 0 is reserved** for the sheet station (infrastructure)
402. **Machine names** must be lowercase alphanumeric with hyphens allowed
413. **Machine numbers** must be unique within a sheet (1-99)
424. **Comments** start with `#` and are ignored
435. **Empty lines** are ignored
44
45## Usage
46
47### Reading the Registry
48
49Machines and tools read the registry to determine their machine number:
50
51```bash
52# Get machine number for 'lldap' in topsheet
53machine_num=$(grep "^lldap=" /volume1/topsheet/station/prod/machine-registry | cut -d= -f2)
54```
55
56### Adding a New Machine
57
581. Edit the registry file on the NAS
592. Add a new line with the next available machine number
603. Ensure no conflicts with existing machines
61
62### Example Workflow
63
64```bash
65# SSH to NAS
66ssh admin@nas.local
67
68# Edit registry for topsheet
69sudo vi /volume1/topsheet/station/prod/machine-registry
70
71# Add new machine
72echo "caddy=6" >> /volume1/topsheet/station/prod/machine-registry
73```
74
75## Integration with tinsnip
76
77The `lib/uid.sh` script automatically consults the machine registry when calculating UIDs:
78
791. If machine name is "station", use machine number 0
802. Otherwise, check the registry file
813. If not found in registry, auto-assign next available number
824. If still not found, return an error
83
84## Future Enhancements
85
86The station machine (M=0) could eventually provide:
87- REST API for machine registration
88- Web UI for registry management
89- Machine discovery endpoints
90- Port allocation tracking