Skip to content

Write the image to a USB stick

The installer is a raw disk image (gateway-installer-<arch>-<ver>.img, or ...-vga.img; see Build the install image). Write it to the whole stick, not to a partition and not as a file copy. Everything on the stick is erased. Any stick of 1 GB or more works.

Flash an image for a site only if its build printed agent carries the release signing key. An image built with ALLOW_UNSIGNED_AGENT=1 printed a BENCH IMAGE warning instead: the devices it installs never take an over-the-air update (see The agent must be a release build).

balenaEtcher (macOS, Windows, Linux)

The simplest option, and it verifies what it wrote.

  1. Install balenaEtcher and open it.
  2. Flash from file: choose the .img.
  3. Select target: choose the USB stick. Check the size and name; Etcher hides system disks by default, so leave that setting alone.
  4. Flash. Wait for the validation pass to finish, then remove the stick.

dd on macOS

diskutil list external physical          # find the stick: /dev/diskN
diskutil unmountDisk /dev/diskN
sudo dd if=gateway-installer-amd64-78.img of=/dev/rdiskN bs=4m
diskutil eject /dev/diskN
  • Run diskutil list before and after plugging the stick in, and make sure N is the disk that appeared. dd to the wrong disk destroys it without asking.
  • Write to /dev/rdiskN (raw device), not /dev/diskN; it is many times faster.
  • dd prints nothing until it finishes. Press Ctrl+T for progress.
  • If dd reports Resource busy, the stick was remounted; run diskutil unmountDisk again.
  • macOS may offer to initialize the stick afterwards ("not readable by this computer"). Choose Ignore or Eject: the stick holds OpenBSD filesystems, which macOS does not read.

dd on Linux and OpenBSD

# Linux: find the stick with lsblk (e.g. /dev/sdX, the whole disk, not sdX1)
sudo dd if=gateway-installer-amd64-78.img of=/dev/sdX bs=4M oflag=direct conv=fsync status=progress

# OpenBSD: the raw whole-disk device of the stick (e.g. sd1 -> /dev/rsd1c)
doas dd if=gateway-installer-amd64-78.img of=/dev/rsdXc bs=1m

Serial and VGA consoles

The image talks to exactly one console, chosen when it was built. Attach the one that matches the image before you boot the box.

Serial image (CONSOLE=serial, the default)

The bootloader, the installer and the installed system all use the first serial port, com0, at 115200 baud, 8 data bits, no parity, 1 stop bit, no flow control. A monitor plugged into such a box shows nothing after the BIOS screen.

You need a USB-serial adapter on your laptop and, for a DB9 COM port on the gateway, a null-modem cable. Then:

# macOS: find the adapter with  ls /dev/cu.*
screen /dev/cu.usbserial-XXXX 115200        # quit: Ctrl+A then K

# Linux
screen /dev/ttyUSB0 115200

# OpenBSD
cu -l /dev/cuaU0 -s 115200                  # quit: ~.

BIOS serial redirection is not required, though it lets you see POST and the boot menu over the same cable.

VGA image (CONSOLE=vga)

Plug in a monitor and a keyboard. The install, the first-boot enrollment and the status box all appear on screen; nothing is written to a COM port. Scroll back with Shift+PgUp.

Warning

A VGA image has a known root console password. Do not leave a box installed from it at a customer site; see Serial or VGA console.

Booting

Boot the gateway from the stick (often a one-time boot menu key such as F7, F11 or F12 at power-on). The install takes a few minutes and reboots on its own. Remove the stick at that first reboot, or the box reinstalls in a loop.