Skip to Content
EdgeNetworkingSetting a Static IP

Setting a Static IP

Edge requests a DHCP address on every physical port by default. Where DHCP is not available or reliable at boot, give the hypervisor a fixed address by supplying cloud-init on a USB drive. Edge reads only the network configuration from the drive and ignores every other cloud-init directive. If you would rather not build a drive, contact support and supply the address, subnet mask, and gateway you want set.

Before You Begin

Collect the following:

  • The MAC address of the port to configure. It is printed on a label on the machine or the port, listed in the server’s firmware setup screen, and shown by your DHCP server alongside its other clients. For a hypervisor already registered on DHCP, the Networks tab of its detail page in the Console shows the MAC address of every adapter.
  • Your address plan. The address and prefix length in CIDR form, the default gateway, and the DNS servers the hypervisor should query.
  • A USB drive. Preparing it erases everything on it.

Prepare the Cloud-Init Drive

Edge reads its configuration from a USB drive formatted as FAT32 with the volume label CIDATA, holding three files at the root of the drive: network-config, user-data, and meta-data. Flash the prepared image, or format a drive by hand.

Flash the Prepared Image

Cloud-Init Drive Image
cidata.img.gz64 KB
Download
  1. Insert the USB drive into your workstation.
  2. Flash cidata.img.gz to the drive with Etcher, which can be downloaded from balena here.
  3. Remove the drive and plug it back in. It appears as CIDATA and holds the three files, ready to edit.

The drive reports a capacity of around 64 MB whatever its physical size. The remainder of the drive is unused.

Format a Drive by Hand

  1. Insert the USB drive into your workstation.

  2. Format the drive as FAT32 with the volume label CIDATA. Edge searches for that label and ignores a drive carrying any other label without reporting an error.

  3. Create network-config, user-data, and meta-data at the root of the drive, not inside a folder. None of the names carry a file extension.

  4. Put a single line in user-data:

    #cloud-config

  5. Leave meta-data empty.

On Windows, turn on File name extensions in File Explorer and set Save as type to All Files when you save. Otherwise Notepad appends .txt to the file name and Edge will not read it. Windows does not offer FAT32 for drives of 32 GB or larger, so use a smaller drive or flash the prepared image instead.

Write the Network Configuration

  1. Open network-config and paste the following template:

    network:
  version: 2
  ethernets:
    id0:
      match:
        macaddress: '52:54:00:12:34:56'
      addresses:
        - 192.168.122.10/24
      routes:
        - to: default
          via: 192.168.122.1
      nameservers:
        addresses: [1.1.1.1, 9.9.9.9]

  2. Replace the four values:

    FieldSet toExample
    macaddressMAC of the port to configure, quoted, colon-separated'52:54:00:12:34:56'
    addressesFixed address and prefix length in CIDR form192.168.122.10/24
    viaDefault gateway192.168.122.1
    nameservers.addressesDNS servers the hypervisor should query[1.1.1.1, 9.9.9.9]

  3. Leave every other line as written.

  • id0 is a label, not an interface name. The macaddress match is what selects the port.
  • Indent with spaces, never tabs. A single tab stops the file being read.
  • Describe only the port that carries the fixed address. Edge bridges every port left out of the file and requests DHCP on it as before.

Apply the Configuration

  1. Eject the drive from your workstation and plug it into the server.
  2. Power the server on, or reboot it if it is already running.
  3. Read the interface line on the server’s screen. (Static) means the drive was applied and the address shown is the one you chose. (DHCP) means the drive was not used.
  4. Leave the drive plugged in until you have registered the hypervisor and created its Storage Pool. See Installing Gallium Edge. Removing the drive before setup finishes reverts the server to DHCP on its next boot.

Once setup is complete the configuration persists on the hypervisor and you can remove the drive. To change the address later, edit network-config, plug the drive back in, and reboot. Edge re-applies the file on every boot the drive is present.

Reach the Hypervisor on a Spare Port

Because every port left out of network-config stays on DHCP, a hypervisor with a fixed address on one port remains reachable through any other port connected to a DHCP network. Two situations rely on this:

  • A static address that does not work. If the address is wrong, or its subnet later moves, connect a spare port to a network with DHCP. The hypervisor returns to the Console on that port while you correct network-config. On a server you cannot reach in person, leave the drive in place so support can correct the configuration remotely.
  • Pre-staging a server before it ships. Set the static address for the network the server is going to. That address is inert on your bench, but a spare port on your own network keeps the hypervisor in the Console, so you can register it, create its Storage Pool, and build its VMs before it leaves. The configured port comes up once the server reaches its destination network.

Troubleshooting

If the server’s screen reports (DHCP) after you plug the drive in:

  • Check the volume label. It must be exactly CIDATA.
  • Check for a hidden extension. network-config.txt is not read. Turn on file name extensions and rename the file.
  • Check the file locations. All three files sit at the root of the drive, not in a subfolder.
  • Check the MAC address. Compare it character by character against the port’s MAC, and confirm you used the port the network cable is in.
  • Check the indentation. A tab anywhere in network-config stops it being read.

If the screen reports a static address other than the one you planned, the drive was read and addresses holds the wrong value.

Managing NetworksCreating a Virtual Machine