Fuchsia

Install Fuchsia on a NUC

This guide provides instructions on how to install Fuchsia on an Intel NUC{:.external} (Next Unit of Computing) device.

The steps are:

  1. Prerequisites.
  2. Build Fuchsia.
  3. Prepare a USB drive.
  4. Enable EFI booting on the NUC.
  5. Install Fuchsia on the NUC.
  6. (Optional) Upload Fuchsia SSH keys to the NUC.

Prerequisites {:#prerequisites .numbered}

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

Note: Fuchsia only supports the NUC configurations listed in Supported system configurations. However, unsupported NUC configurations may also work with Fuchsia. For more information on experimental setups, see Experimental hardware.

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)

Note: The 2. Build Fuchsia and 3. Prepare a USB drive sections do not require a NUC device, so you can complete these sections prior to obtaining a NUC device. However, you will need a USB flash drive for the 3. Prepare a USB drive section.

Build Fuchsia {:#build-fuchsia .numbered}

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

To build Fuchsia for NUC installation, do the following:

  1. Set your build configuration to workstation_eng.x64 and include the recovery package (recovery-installer):

    fx set workstation_eng.x64 --with //build/images/recovery:recovery-installer

  2. Build Fuchsia:

    fx build

    Building Fuchsia can take up to 90 minutes.

Prepare a USB drive {:#prepare-usb .numbered}

You need to prepare a bootable USB drive that runs the Fuchsia installer. Later in the Install Fuchsia on the NUC section, you will use this USB drive to boot your NUC into the Fuchsia installer.

Important: The instructions below require that you've completed the build in the previous Build Fuchsia section.

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 bootable USB drive:

    fx mkinstaller -v {{ "<var>" }}PATH_TO_USB_DRIVE{{ "</var>" }}

    Replace PATH_TO_USB_DRIVE with the path to the USB drive from the step above.

    The example command below selects the /dev/sda path:

    $ fx mkinstaller -v /dev/sda

    When finished, the command prints output similar to the following in the end:

    $ fx mkinstaller -v /dev/sda
mkinstaller: WARNING: Changing ownership of /dev/sda to alice
[sudo] password for alice:
...
mkinstaller: INFO:    Writing image fvm.sparse.blk to partition storage-sparse...
mkinstaller: INFO:      Wrote 835.6M in 35.55s, 23.5M/s
mkinstaller: INFO: Done.
mkinstaller: INFO: Ejected USB disk

  4. Unplug the USB drive from the workstation.

Enable EFI booting on the NUC {:#enable-efi-booting .numbered}

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.

        Note: If the above options don‘t appear, your system doesn’t support legacy boot and those steps can be skipped.

        • 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.

Install Fuchsia on the NUC {:#install-fuchsia .numbered}

Use the bootable USB drive to boot your NUC into the Fuchsia installer. It then installs the Workstation image (which was built in the Build Fuchsia section) to the NUC.

To install Fuchsia on your NUC, do the following:

  1. Plug the bootable USB drive into the NUC.

  2. Reboot your NUC.

    The NUC boots into the Fuchsia Workstation Installer (with a pink background).

  3. Press Enter to select the Install from USB option.

  4. Press Enter on other prompts to continue.

  5. Once the installation completes, unplug the USB drive from the NUC device.

  6. Reboot the NUC device.

    The NUC is now booted into Fuchsia’s Workstation.

Note: 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 in Appendices.

(Optional) Upload Fuchsia SSH keys to the NUC {:#upload-fuchsia-ssh-keys .numbered}

If you plan on using this NUC device for Fuchsia development, you need to flash a Fuchsia image to the NUC device from your host machine, which in turn uploads the Fuchsia-specific SSH keys to the NUC. Once those Fuchsia-specific SSH keys are uploaded to the NUC, you can perform ffx-based workflows on the NUC from your host machine.

To upload Fuchsia SSH keys to the NUC, do the following:

  1. Complete the steps in the Flash a new Fuchsia image to the NUC section in Appendices.

  2. To verify that you can connect to the NUC from the host machine, run the following command:

    ffx target show

    This command prints output similar to the following:

    $ ffx target show
Target:
    Name: "fuchsia-54b2-0389-644b"
    SSH Address: "fe81::55b1:2ff2:fe34:567b%en10:22"
Board:
    Name: "default-board"
    Revision: "1"
    Instruction set: "x64"
...

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:

Flash a new Fuchsia image to the NUC

Once a NUC is running Fuchsia, you can use Fuchsia's flashing mechanism to provision a new Fuchsia image to the NUC.

To flash a Fuchsia image to your NUC, do the following:

  1. Connect the NUC directly to the workstation using an Ethernet cable.

    (Or you can also connect the NUC to a router or WiFi modem in the same Local Area Network as the workstation.)

    Note: Network booting only works with the NUC's built-in Ethernet port. Netbooting with an USB port (via an Ethernet-to-USB adapter) is not supported.

  2. Reboot your NUC.

  3. On Fuchsia's boot screen, press the f key to select the fastboot option.

    Once the NUC is in Fastboot mode, it prints Fastboot TCP is ready on the screen.

  4. On your workstation, discover the NUC in Fastboot mode:

    ffx target list

    This command prints output similar to the following:

    $ ffx target list
NAME                      SERIAL       TYPE       STATE       ADDRS/IP                           RCS
fuchsia-54b2-0389-644b    <unknown>    Unknown    Fastboot    [fe81::55b1:2ff2:fe34:567b%en10]    N

    Verify that the device's state is Fastboot.

  5. Flash a new Fuchsia image to the NUC:

    Note: To build a new Fuchsia image, see the Build Fuchsia section above.

    fx flash

    If you have multiple devices connected to the host machine previously, you may need to explicitly specify the name of the NUC device, for example:

    fx flash -s fuchsia-54b2-0389-644b

    When finished, the NUC reboots and starts running the new Fuchsia image.

Remote management of NUC devices {:#remote-management-of-nuc-devices}

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

Note: This assumes you're using NUC connected to the EdgeRouter. If your networking setup is different, you may need a different network configuration.

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.

    Note: The password must be at least 8 characters long, contain both lowercase and uppercase characters, at least one digit and at least one non alphanumeric character (“_” is considered alphanumeric).

    Tip: If you choose a password that is exactly 8 characters long, you can use the same password as the VNC password below.

  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{:.external} 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.

Note: The password used for VNC_PASSWORD must be exactly 8 characters long, must contain both lowercase and uppercase characters, at least one digit and at least one non alphanumeric character.

  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.

Note: The NUC needs to be plugged in to a monitor with a HDMI cable to accept VNC connections.

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