vmnet-brokerctl — A CLI for declarative vmnet management

[nirs]

vmnet-brokerctl — A CLI for declarative vmnet management

Problem statement

While the vmnet-broker daemon handles the lifecycle of virtual bridges,
manual management of JSON configuration files in /etc/vmnet-broker.d/ is
error-prone. Admins lack a native way to:

1. Validate subnets against the physical host network before deployment.
2. Visualize the total network map and identify overlaps.
3. Standardize the creation of new network segments without manual JSON
   editing.

Suggested solution

Introduce vmnet-brokerctl, a Swift-based CLI tool that serves as the administrative
interface for the broker. It will share the same core networking logic as the
daemon to ensure that "validation" in the CLI perfectly matches "execution" in
the broker.

Command structure

The tool will follow the standard Unix subcommand pattern:

vmnet-brokerctl list

Displays all configured networks, their gateways, and their calculated IP
ranges using the "Magic Number" logic.

vmnet-brokerctl check

A pre-flight validation tool. It scans the configuration directory and:

• Flags internal overlaps (e.g., two /28 subnets sharing a block).
• Flags collisions with live physical interfaces (e.g., en0).
• Returns a non-zero exit code on failure for use in scripts.

vmnet-brokerctl add [name]

An interactive or flag-based helper to generate a valid configuration.
Arguments:

• --ip: The gateway IP (e.g., 192.168.2.1)
• --mask: The subnet mask (e.g., 255.255.255.240)

Technical trade-offs and disadvantages

Pros

• Shared logic: By using Swift for both the broker and vmnet-brokerctl, the
  overlap detection code is written once and remains consistent.
• Safety: The add command can perform a "dry-run" check against live
  system routing tables before ever writing a file to disk.
• Improved UX: Provides network engineers with familiar feedback (ranges,
  masks, and CIDR notation) that is currently missing from vmnet.

Cons

• Permissions: Writing to /etc/vmnet-broker.d/ requires sudo. The CLI
  must handle permission errors gracefully or prompt for escalation.
• Swift Runtime: While natively supported on macOS, it requires the Swift
  Argument Parser dependency, which must be managed during the build process.

Example output

$ vmnet-brokerctl list

NETWORK        GATEWAY        RANGE                        STATUS
lima-net       192.168.105.1  192.168.105.0 - 105.255      ACTIVE
tart-net       192.168.32.1   192.168.32.0  - 32.15        ACTIVE
minikube       192.168.32.17  192.168.32.16 - 32.31        ACTIVE