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

```bash
# 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

```bash
# 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