nmconnection-tools

Generate and test NetworkManager .nmconnection keyfiles for dedicated servers.

Scripts

Script	Purpose
hetzner-nmconnection.sh	Generate keyfile from Hetzner Robot API
leaseweb-nmconnection.sh	Generate keyfile from Leaseweb API
test-nmconnection.sh	Test a keyfile with automatic rollback

Dependencies

• curl, jq (generator scripts)
• NetworkManager (test script)

Usage

Hetzner

Export Robot API credentials (obtained via ops) and the server number.

export ROBOT_USER=xxx ROBOT_PASS=xxx
export SERVER_NUMBER=12345

Write to stdout to inspect results:

curl -fsSL https://raw.githubusercontent.com/balena-io-experimental/nmconnection-tools/main/hetzner-nmconnection.sh \
  | bash -s "${SERVER_NUMBER}"

If visual inspection passes, write results to a temp file:

curl -fsSL https://raw.githubusercontent.com/balena-io-experimental/nmconnection-tools/main/hetzner-nmconnection.sh \
  | bash -s "${SERVER_NUMBER}" > /tmp/public-static.nmconnection

Leaseweb

Export Leaseweb API key (obtained via ops) and the numerical bareMetalId of the server.

export LSW_API_KEY=xxx
export SERVER_ID=12345

Write to stdout to inspect results:

curl -fsSL https://raw.githubusercontent.com/balena-io-experimental/nmconnection-tools/main/leaseweb-nmconnection.sh \
  | bash -s "${SERVER_ID}"

If visual inspection passes, write results to a temp file:

curl -fsSL https://raw.githubusercontent.com/balena-io-experimental/nmconnection-tools/main/leaseweb-nmconnection.sh \
  | bash -s "${SERVER_ID}" > /tmp/public-static.nmconnection

Testing

curl -fsSL https://raw.githubusercontent.com/balena-io-experimental/nmconnection-tools/main/test-nmconnection.sh \
  | bash -s /tmp/public-static.nmconnection

The test script loads the keyfile into NetworkManager, runs connectivity checks (IPv4, IPv6, DNS), then automatically reverts to the original connection after ~15 seconds. Results are written to /tmp/nm-test-result.

Deploying to balenaOS

Copy to the balenaOS boot partition:

mkdir -p /mnt/boot && mount /dev/md/balena1 /mnt/boot
cp /tmp/public-static.nmconnection /mnt/boot/system-connections/public-static.nmconnection
umount /mnt/boot