Release candidate · QEMU verified · Not bare-metal qualified
Download RC
Documentation

Install and recovery

← All docs · Raw Markdown

Installation and recovery (NurRouterOS 0.4.0 RC)

Scope and honesty

This document describes actual installer, recovery, and first-boot behavior from the sources under appliance/installer/ and files/etc/uci-defaults/.

Documentation is not acceptance proof. Treat each claim as verified only when an executed evidence file names the exact artifact SHA-256.

  • Bare-metal is not qualified for this RC unless separately evidenced.
  • QEMU/KVM lab installs are the supported verification surface.

Artifacts

Build with ./build.sh from nurrouteros/ (do not set NUR_SSH_AUTHORIZED_KEY_FILE for release candidates). Outputs under output/<OpenWrt>/appliance/:

Artifact Path pattern
Hybrid BIOS/UEFI installer ISO iso/nurrouteros-<product>-installer.iso
RAW / QCOW2 (BIOS|UEFI × ext4|squashfs) *.raw / *.qcow2
Manifest + package inventory manifest.json, payload/SHA256SUMS

Never ship signing private keys, management SSH private keys, production credentials, pre-generated device IDs, or embedded authorized_keys in distributable images.

Boot parameters (kernel cmdline)

All of the following are parsed by appliance/installer/nur-install and/or selected by GRUB (appliance/installer/grub.cfg):

Parameter Values Effect
nur.mode install | recovery Which program owns the console (init + GRUB entries)
nur.interactive 0 | 1 0 disables prompts (unattended); default 1
nur.autoreboot 0 | 1 Reboot after successful install
nur.dryrun 1 Validate only; never write
nur.disk /dev/sdX etc. Explicit target disk (required when non-interactive)
nur.confirm ERASE-<diskbasename> Unattended confirmation token
nur.firmware auto | bios | uefi Firmware layout selection
nur.rootfs ext4 | squashfs Payload variant to write
nur.grow yes | no Grow rootfs after write (ext4 only)

GRUB menu entries set: interactive install; unattended install (nur.interactive=0 nur.autoreboot=1); recovery; dry-run install (nur.dryrun=1).

CLI equivalents: --disk, --confirm, --firmware, --rootfs, --no-grow, --non-interactive, --autoreboot, --dry-run.

ext4 versus squashfs

Topic ext4 squashfs
Payload Writable root filesystem image Compressed read-only root + overlay model as shipped
Growth Supported when nur.grow=yes (default). Uses parted + resize2fs after the payload write. Not supported. Installer refuses nur.grow=yes / missing --no-grow. Pass nur.grow=no.
Persistence Config and state live on the grown rootfs partition Persistence depends on the squashfs/overlay layout in the payload; growth is not available to enlarge the rootfs image
Recovery password reset Mounts the ext4 rootfs read-write to edit /etc/shadow Reset path requires an ext4-mounted rootfs; if the installed root cannot be mounted as ext4, recovery reports an error and writes nothing
Install record Written to /etc/nurrouter-installer/install-record.json on the mounted rootfs after a successful write Same path when the rootfs can be mounted

Interrupted writes leave the disk incomplete. Treat as failed install: wipe and reinstall with a fresh confirmation. Do not attempt to “repair” a half-written payload in place.

Install procedure

  1. Attach the installer ISO and an empty (or explicitly disposable) target disk.
  2. Boot the installer (BIOS El Torito or UEFI BOOTX64.EFI).
  3. Select install, or boot unattended with nur.disk + nur.confirm=ERASE-<name>.
  4. Confirm the destructive wipe (ERASE-<diskbasename>). Wrong token / timeout → nothing written.
  5. Payload is SHA-256 verified before and after the write.
  6. For squashfs: pass nur.grow=no. For ext4: growth runs unless nur.grow=no.
  7. Remove install media and boot the installed disk.

Dry-run (nur.dryrun=1) never writes. Source-disk / mounted-target refusal paths also write nothing.

First-boot identity and credentials (actual behavior)

On first boot, files/etc/uci-defaults/98-nur-device-id and 99-nurrouteros run once:

  1. Unique device ID written to /etc/nurrouter/device-id (nur-<32 hex>). Two independently initialized appliances must differ.
  2. Unique SSH host keys generated under /etc/dropbear/ when missing.
  3. Unique root password generated from /dev/urandom and stored only in /etc/nurrouter/bootstrap/credentials (mode 0600), together with a bootstrap_token. There is no universal default password and no packaged authorized_keys.
  4. Remote password SSH is off (PasswordAuth / RootPasswordAuth = off). Dropbear is bound to the management interface.
  5. LuCI/uhttpd is disabled until operators enroll and deliberately enable it.
  6. Local console enrollment helper: nur-console-enroll:
    • status — device id, host key fingerprint, enrollment state
    • show-bootstrap — print local bootstrap credentials (console only)
    • enroll-key /path/to/wincontrol.pub — append a forced-command nur-mgmt key

Do not rely on “set a root password before exposing SSH” as the primary control. Release images deny unauthenticated remote administration by default; enrollment is the intended path for WinControl.

Disk clones copy device-id and any local license file. That is not a supported ownership transfer — use the licensing transfer workflow.

Recovery console

Boot installer media with nur.mode=recovery (GRUB: “recovery console”).

Menu action Writes to disk?
Emergency shell No (installer media remains read-only at /mnt/cdrom)
List disks / installation records No — mounts candidate rootfs read-only
Verify installer media integrity No — reads /mnt/cdrom/payload only
Reset root password Yes — after ERASE-<disk> confirmation: RW-mounts ext4 rootfs, rewrites /etc/shadow, keeps /etc/shadow.nur-backup
Install / reinstall Yes — hands off to nur-install (full destructive payload write after confirmation)
Reboot / power off No disk content write beyond sync

Interrupted-install detection

Listing disks mounts each candidate partition read-only and inspects /etc/nurrouter-installer/install-record.json. Corrupt or incomplete records (missing fields, or record present without a recognizable NurRouterOS root) are reported as diagnostics. Documented operator response: wipe and reinstall with a fresh ERASE-<disk> confirmation — not in-place repair.

Password reset and SSH

Password reset is local-console only (no network listener). Clearing the password does not enable remote password SSH; Dropbear password authentication remains off until an operator explicitly changes Dropbear policy. Use the local console and nur-console-enroll to restore management access.

Safe Mode

Safe Mode / watchdog restore of the last confirmed UCI backup remains local to the appliance and does not require WinControl connectivity. Licensing failure modes must not block Safe Mode or local recovery (see LICENSING.md).

Safety regressions to re-verify per artifact SHA-256

  • Wrong-disk / no-confirm refusal (nothing written)
  • Corrupt install-record diagnostics (read-only)
  • Interrupted install → wipe + reinstall
  • squashfs + nur.grow=yes refused
  • UEFI and BIOS boot of the installed image
  • Two independently initialized appliances: distinct device IDs, distinct SSH host keys, empty management authorized_keys, password SSH off