Install Fuchsia on a NUC using Zedboot (Legacy)

This guide provides instructions on how to install Fuchsia on an Intel NUC (Next Unit of Computing) device using a Zedboot -based bootable USB drive.

The steps are:

  1. Prerequisites.
  2. Build Fuchsia.
  3. Prepare a Zedboot-based bootable USB drive.
  4. Enable EFI booting on the NUC.
  5. Install Fuchsia on the NUC.

1. Prerequisites

Before you start installing Fuchsia on a NUC device, make sure that you've completed the following tasks:

Set up the Fuchsia development environment

To set up the Fuchsia development environment on your workstation, complete the Get started with Fuchsia guide.

Get parts

The following parts are required for this guide:

  • A NUC device (see example models)
  • A USB 3.0 flash drive
  • A keyboard
  • A mouse (Optional)
  • A monitor with an HDMI port
  • An HDMI cable
  • An Ethernet cable
  • A Phillips-head screwdriver (with a magnetic tip)

2. Build Fuchsia

Installing Fuchsia on a NUC device requires that you build a Workstation image (workstation_eng.x64) and generate build artifacts on your workstation.

To build Fuchsia for NUC installation, do the following:

  1. Set your build configuration to workstation_eng.x64:

    fx set workstation_eng.x64
    
  2. Build Fuchsia:

    fx build
    

    Building Fuchsia can take up to 90 minutes.

3. Prepare a Zedboot-based bootable USB drive

You need to prepare a bootable USB drive that is based on Fuchsia's Zedboot. Later in the Install Fuchsia on the NUC section, you will use this USB drive to boot your NUC into the Zedboot mode.

To prepare a bootable USB drive, do the following:

  1. Plug the USB drive into your workstation.

  2. Identify the path to the USB drive:

    fx list-usb-disks
    

    This command prints output similar to the following:

    $ fx list-usb-disks
    /dev/sda - My Example USB Disk
    
  3. Create a Zedboot-based bootable USB drive:

    fx mkzedboot PATH_TO_USB_DRIVE
    

    Replace PATH_TO_USB_DRIVE with the path to the USB drive from the step above, for example:

    $ fx mkzedboot /dev/sda
    

    This command creates a Zedboot-based bootable USB drive and dismounts the USB drive.

  4. Unplug the USB drive from the workstation.

4. Enable EFI booting on the NUC

Update your NUC's BIOS setup so that it can boot from a USB drive.

The steps are slightly different depending on which BIOS is included in your system:

  • Visual BIOS:

  • Aptio V BIOS:

Visual BIOS

To enable EFI (Extensible Firmware Interface) booting on your NUC, do the following:

  1. Reboot your NUC.
  2. To enter the BIOS setup, press F2 while booting.
  3. Click the Advanced button.
  4. Click the Boot tab.
  5. Confirm the following boot configuration:

    • Under the Boot Priority tab:

      • UEFI Boot is checked.
      • Legacy Boot is unchecked.

    • Under the Boot Configuration tab:

      • In the UEFI Boot window:
      • Boot USB Devices First is checked.
      • Boot Network Devices Last is checked.
      • Unlimited Network Boot Attempts is checked.
      • In the Boot Devices window:
      • USB is checked.
      • Network Boot is set to UEFI PXE & iSCSI.

    • Under the Secure Boot tab:

      • Secure Boot is unchecked.

  6. To save and exit BIOS, press F10 and click Yes.

Aptio V BIOS

To enable EFI (Extensible Firmware Interface) booting on your NUC, do the following:

  1. Reboot your NUC.
  2. To enter the BIOS setup, press F2 while booting.
  3. Click the Boot tab.
  4. Confirm the following boot configuration:

    • In the Secure Boot section:

      • Secure Boot is set to Disabled.

    • In the Boot Priority section:

      • UEFI Boot is checked.
      • Legacy Boot is unchecked.
      • Boot USB Devices First is checked.
      • Boot Network Devices Last is checked.
      • Unlimited Boot to Network Attempts is checked.
      • USB is checked.
      • Network Boot is set to UEFI PXE & iSCSI.

  5. To save and exit BIOS, press F10 and click Ok.

5. Install Fuchsia on the NUC

Use the Zedboot-based bootable USB drive to boot your NUC into the Zedboot mode. Then pave the Workstation prebuilt image from your workstation to the NUC to install Fuchsia for the first time.

On a NUC, Fuchsia boots the device using a chain of bootloaders. The instructions in this section creates a bootable USB drive for Fuchsia that handles the first two steps in the bootloader chain: Gigaboot and Zedboot . Gigaboot is a UEFI boot shim with some limited functionality (for instance, netbooting and flashing). By default, Gigaboot chains into Zedboot, which is a bootloader built on top of Zircon. Zedboot then can boot the device into a Fuchsia product or allow you to pave a Fuchsia image to the device.

To install Fuchsia on your NUC, do the following:

  1. Plug the Zedboot-based bootable USB drive into the NUC.

  2. Connect the NUC directly to the workstation using an Ethernet cable (or connect the NUC to a router or WiFi modem in the same Local Area Network as the workstation).

  3. Reboot your NUC.

    The NUC boots into Fuchsia's Zedboot mode, displaying Zedboot's signature blue screen.

  4. On the Zedboot screen, press Alt + F3 to switch to a command-line prompt.

  5. On the NUC, view the HDD or SSD's block device path:

    lsblk
    

    Take note of the block device path (for example, the path might look like /dev/sys/platform/pci/00:17.0/ahci/sata0/block).

  6. On the NUC, wipe and initialize the partition tables of the NUC:

    install-disk-image wipe-partition-tables --block-device <BLOCK_DEVICE_PATH>
    
    install-disk-image init-partition-tables --block-device <BLOCK_DEVICE_PATH>
    

    Replace BLOCK_DEVICE_PATH with the block device path from the step above, for example:

    $ install-disk-image wipe-partition-tables --block-device /dev/sys/platform/pci/00:17.0/ahci/sata0/block
    $ install-disk-image init-partition-tables --block-device /dev/sys/platform/pci/00:17.0/ahci/sata0/block
    
  7. On your workstation, pave the Fuchsia image to the NUC:

    fx pave
    
  8. When the paving is finished, unplug the USB drive from the NUC.

Fuchsia is now installed on your NUC. When you reboot the device, it will load Gigaboot, Zedboot, and Fuchsia all from your device's storage. Therefore, you no longer need to keep the USB drive plugged in.

Later, if you need to install a new version of Fuchsia (for instance, after re-building a new Workstation image using fx build), see Flash a new Fuchsia image to the NUC.

Troubleshoot

Keyboard not working after Zedboot

After plugging the Zedboot USB drive to the NUC, if you notice that the keyboard on the NUC is not working, then skip Step 4 through 6 and perform the following workaround instead:

  1. On your workstation, try to install Fuchsia on the NUC:

    fx pave
    

    This command may fail due to the partition tables issue on the NUC.

  2. View the kernel logs:

    fx klog
    

    In the logs, look for an error message similar to the following:

    Unable to find a valid GPT on this device with the expected partitions. Please run *one* of the following command(s):
    fx init-partition-tables /dev/sys/platform/pci/00:17.0/ahci/sata0/block
    
  3. To initialize the partition tables on the NUC, run the suggested command in the logs, for example:

    $ fx init-partition-tables /dev/sys/platform/pci/00:17.0/ahci/sata0/block
    
  4. Now, to install Fuchsia on the NUC, run the following command again:

    fx pave
    

Paving or netbooting not working after Zedboot

After issuing the fx pave command, if paving does not complete, make sure the Ethernet cable is directly connected to the Ethernet port of the NUC, and is not using an Ethernet-to-USB adapter to connect to a USB port of the NUC – even though an Ethernet-to-USB adapter works after Fuchsia has been paved (for instance, when doing fx ota), the USB port doesn't work with Zedboot when paving.

Address already in use

When you run the fx pave command, you may run into the following error:

2022-01-20 15:23:00 [bootserver] cannot bind to [::]:33331 48: Address already in use
there may be another bootserver running

When you see this error, do the following:

  1. Check the processes that are currently using the port 33331:

    sudo lsof -i:33331
    

    This command prints output similar to the following:

    $ sudo lsof -i:33331
    COMMAND   PID USER   FD   TYPE             DEVICE SIZE/OFF NODE NAME
    ffx     69264 alice  15u  IPv6 0xb12345ed61b7e12d      0t0  UDP *:diamondport
    
  2. Terminate all the processes in the list, for example:

    kill 69264
    

Appendices

Supported NUC models

For GPU support, get a NUC7 (Kaby Lake) or NUC8 (Coffee Lake), or a higher generation.

The list below shows some example models:

Install RAM and SSD to a NUC device

Some NUC devices do not come with RAM or an SSD. In which case, you need to install them manually.

Figure 1. A NUC device and RAM and SSD sticks.

The table below shows some RAM and SSD example models:

Item Link Notes
RAM Crucial 8GB DDR4-2400 SODIMM Works fine.
SSD Samsung SSD 850 EVO SATA M.2 250GB Works fine.
SSD ADATA Ultimate SU800 M.2 2280 3D NAND SSD Works fine.
SSD CRUCIAL MX300 SSD Works fine, but is discontinued.

To install the RAM and SSD on your NUC, do the following:

  1. Remove the Phillips screws on the bottom feet of the NUC.

  2. Install the RAM.

  3. Remove the Phillips screws that would hold the SSD in place (a Phillips screwdriver with a magnetic tip is useful here).

  4. Install the SSD.

  5. Mount the SSD in place using the screws from Step 3.

  6. Put the bottom feet and screws back in.

  7. Plug the power, monitor (using HDMI), and keyboard into the NUC.

Remote management of NUC devices

To enable remote management, including KVM, you need to configure Intel AMT (Active Management Technology).

First, configure Intel ME on your NUC:

  1. Reboot your NUC.
  2. Enter Intel ME settings by pressing Ctrl+P on the boot screen.
  3. Select MEBx Login
  4. Set up a new password, the default one is admin.

  5. Configure network:

    1. Select Intel(R) AMT Configuration.
    2. Unconfigure existing network settings:

      1. Select Unconfigure Network Access
      2. Select Full Unprovision
      3. Press Y to confirm.
    3. Select Network Setup > TCP/IP Settings > Wired LAN IPV4 Configuration.

    4. Set DHCP Mode to Disabled.

    5. Set IPV4 Address to an address reachable from your host machine via the EdgeRouter.

      On your host machine, run ifconfig and find the entry that corresponds to the EdgeRouter, for example:

      $ ifconfig
      enx00e04c0c13ba: flags=4163<UP,BROADCAST,RUNNING,MULTICAST>  mtu 1500
              inet 192.168.42.86  netmask 255.255.255.0  broadcast 192.168.42.255
              ...
      

      In this case, you could try using the address 192.168.42.20

    6. Set Subnet Mask Address to the netmask of your host machine to EdgeRouter connection, for example 255.255.255.0.

    7. Press Esc until you return to Intel(R) AMT Configuration.

    8. Select Activate Network Access and press Y to confirm.

    9. Exit Intel ME settings and save your changes.

Now, configure the amtctrl command-line utility on your host machine:

These instructions assume you have set some environment variables:

  • AMT_HOST: The IPv4 address you configured in the Intel ME settings.
  • AMT_PASSWORD: The password you chose for Intel ME.
  • VNC_PASSWORD: A password for accessing the NUC over VNC.
  1. Clone the amtctrl repository:

    git clone https://github.com/sdague/amt
    
  2. Install amtctrl:

    cd amt && sudo ./setup.py install
    
  3. Configure NUC IP address and passwords:

    amtctrl set -V $VNC_PASSWORD nuc $AMT_HOST $AMT_PASSWORD
    
  4. Enable VNC:

    amtctrl nuc vnc
    

Now, you can access the NUC from your host machine using any VNC client by connecting to the IP address set in AMT_HOST. Enter the password set in VNC_PASSWORD when prompted.

You can also turn on, turn off or reboot the NUC with the following terminal commands:

  • To turn on the NUC:

    amtctrl nuc on
    
  • To turn off the NUC:

    amtctrl nuc off
    
  • To reboot the NUC:

    amtctrl nuc reboot