| # Create a bootable Fuchsia image |
| |
| ## Overview |
| |
| The `mkinstaller` script produces a bootable disk image from a build which can be used to |
| install Fuchsia to a target machine. It supports creating installation images |
| for x64 EFI-based devices (the x64 product configuration), and coreboot-based devices |
| (the chromebook-x64 configuration), depending on what has been built. |
| |
| |
| ## Implementation |
| |
| Mkinstaller can write an image directly to a USB disk, or it can produce a new |
| image file on the host machine, which can then be written to install media using |
| `dd` or similar. The mkinstaller script determines the images to be written to |
| disk based on `${FUCHSIA_BUILD_DIR}/images.json`, and then writes each partition |
| to disk, labelled according to the “name” field of the entry in images.json. |
| |
| |
| ## Use the installer |
| |
| After you complete a build, you can create an installer image with |
| `fx mkinstaller /path/to/usb`. |
| |
| Note: To see a full list of options, run `fx mkinstaller -h`. |
| |
| Follow the steps below to install Fuchsia: |
| |
| 1. To access the installer, boot your computer or virtual machine from the USB. |
| |
| You should see a blue boot screen. |
| |
| 1. To access the Fuchsia shell, press alt+tab. |
| |
| These are the ways you can install Fuchsia: |
| |
| * [Automatic installation](#automatic_installation) |
| * [Manual installation](#manual_installation) |
| |
| ### Automatic installation |
| |
| 1. Run `installer` to launch the installer. |
| |
| <pre class="prettyprint"> |
| <code class="devsite-terminal">installer</code> |
| <span class="no-select">Bootloader vendor = Intel Corp. |
| Please select the disk you want to install Fuchsia to: |
| [0] /dev/sys/pci/00:17.0/ahci/sata2/block (119G) |
| Enter a selection (0..0): |
| </span> |
| </pre> |
| |
| You will see a list of disks, along with their sizes. |
| |
| |
| 1. Type in the number corresponding to the disk you wish to install Fuchsia on, and press ENTER. |
| |
| Note: What you type in won't be displayed until you press ENTER. |
| |
| <pre class="prettyprint"> |
| <span class="no-select"> |
| Enter a selection (0..0): 0 |
| Using /dev/sys/pci/00:17.0/ahci/sata2/block as installation target. |
| |
| WARNING: Installing Fuchsia will WIPE YOUR DISK. Make sure you've backed |
| everything up before proceeding! |
| Do you wish to proceed? (yes/[no]) |
| </span> |
| </pre> |
| |
| 1. Confirm that you want to continue. The installer will wipe your disk, set up |
| the Fuchsia partition tables, and install Fuchsia to your disk. The installer |
| will show its progress as it installs, and exit once the installation is |
| complete. |
| |
| <pre class="prettyprint"> |
| <span class="no-select"> |
| Do you wish to proceed? (yes/[no]) yes |
| Wiping old partition tables... |
| Initializing Fuchsia partition tables... |
| Success. |
| Partition[src=/dev/sys/pci/00:14.0/xhci/usb-bus/001/001/ifc-000/ums/lun-000/block/part-002/block, pave_type=Bootloader]... OK |
| Partition[src=/dev/sys/pci/00:14.0/xhci/usb-bus/001/001/ifc-000/ums/lun-000/block/part-003/block, pave_type=Asset { type: Kernel, config: A }, asset=Kernel, config=A]... OK |
| Partition[src=/dev/sys/pci/00:14.0/xhci/usb-bus/001/001/ifc-000/ums/lun-000/block/part-003/block, pave_type=Asset { type: Kernel, config: A }, asset=Kernel, config=A] [-B]... OK |
| Partition[src=/dev/sys/pci/00:14.0/xhci/usb-bus/001/001/ifc-000/ums/lun-000/block/part-004/block, pave_type=Asset { type: Kernel, config: Recovery }, asset=Kernel, config=Recovery]... OK |
| Partition[src=/dev/sys/pci/00:14.0/xhci/usb-bus/001/001/ifc-000/ums/lun-000/block/part-005/block, pave_type=Volume]... OK |
| </span> |
| </pre> |
| |
| 1. Unplug the installation USB drive. |
| |
| 1. Reboot your machine. |
| |
| <pre class="prettyprint"> |
| <code class="devsite-terminal">dm reboot</code> |
| </pre> |
| |
| ### Manual installation |
| |
| |
| 1. Run `lsblk` to determine the main disk of the target machine. |
| |
| <pre class="prettyprint"> |
| <code class="devsite-terminal">lsblk</code> |
| <span class="no-select">ID SIZE TYPE LABEL FLAGS DEVICE |
| 000 28G RE /dev/sys/pci/00:14.0/xhci/usb-bus/001/001/ifc-000/ums/lun-000/block |
| 001 63M efi-system zedboot-efi RE /dev/sys/pci/00:14.0/xhci/usb-bus/001/001/ifc-000/ums/lun-000/block/part-000/block |
| 002 1M cros-data efi RE /dev/sys/pci/00:14.0/xhci/usb-bus/001/001/ifc-000/ums/lun-000/block/part-001/block |
| 003 25M cros-data zircon-a RE /dev/sys/pci/00:14.0/xhci/usb-bus/001/001/ifc-000/ums/lun-000/block/part-002/block |
| 004 22M cros-data zircon-r RE /dev/sys/pci/00:14.0/xhci/usb-bus/001/001/ifc-000/ums/lun-000/block/part-003/block |
| 005 321M cros-data storage-sparse RE /dev/sys/pci/00:14.0/xhci/usb-bus/001/001/ifc-000/ums/lun-000/block/part-004/block |
| 006 119G /dev/sys/pci/00:17.0/ahci/sata2/block |
| </span> |
| </pre> |
| |
| In this case, `/dev/sys/pci/00:17.0/ahci/sata2/block` is the main disk of the |
| target machine. |
| |
| 1. Run `install-disk-image` to wipe and initialize the partition tables on the |
| target machine. Replace `/dev/sys/pci/00:17.0/ahci/sata2/block` with the path |
| you determined using the `lsblk` command. |
| |
| <pre class="prettyprint"> |
| <code class="devsite-terminal">install-disk-image init-partition-tables --block-device <var>/dev/sys/pci/00:17.0/ahci/sata2/block</var></code> |
| <span class="no-select"> |
| disk-pave: init-partition-tables operation succeeded. |
| </span> |
| </pre> |
| |
| 1. Run `lsblk` to confirm the state of the disks: |
| |
| <pre class="prettyprint"> |
| <code class="devsite-terminal">lsblk</code> |
| <span class="no-select"> |
| ID SIZE TYPE LABEL FLAGS DEVICE |
| 000 28G RE /dev/sys/pci/00:14.0/xhci/usb-bus/001/001/ifc-000/ums/lun-000/block |
| 001 63M efi-system zedboot-efi RE /dev/sys/pci/00:14.0/xhci/usb-bus/001/001/ifc-000/ums/lun-000/block/part-000/block |
| 002 1M cros-data efi RE /dev/sys/pci/00:14.0/xhci/usb-bus/001/001/ifc-000/ums/lun-000/block/part-001/block |
| 003 25M cros-data zircon-a RE /dev/sys/pci/00:14.0/xhci/usb-bus/001/001/ifc-000/ums/lun-000/block/part-002/block |
| 004 22M cros-data zircon-r RE /dev/sys/pci/00:14.0/xhci/usb-bus/001/001/ifc-000/ums/lun-000/block/part-003/block |
| 005 321M cros-data storage-sparse RE /dev/sys/pci/00:14.0/xhci/usb-bus/001/001/ifc-000/ums/lun-000/block/part-004/block |
| 006 119G /dev/sys/pci/00:17.0/ahci/sata2/block |
| 052 16M efi-system efi-system /dev/sys/pci/00:17.0/ahci/sata2/block/part-000/block |
| 053 64M zircon-a zircon-a /dev/sys/pci/00:17.0/ahci/sata2/block/part-001/block |
| 054 64M zircon-b zircon-b /dev/sys/pci/00:17.0/ahci/sata2/block/part-002/block |
| 055 96M zircon-r zircon-r /dev/sys/pci/00:17.0/ahci/sata2/block/part-003/block |
| 056 64K vbmeta_a vbmeta_a /dev/sys/pci/00:17.0/ahci/sata2/block/part-004/block |
| 057 64K vbmeta_b vbmeta_b /dev/sys/pci/00:17.0/ahci/sata2/block/part-005/block |
| 058 64K vbmeta_r vbmeta_r /dev/sys/pci/00:17.0/ahci/sata2/block/part-006/block |
| 059 4K misc misc /dev/sys/pci/00:17.0/ahci/sata2/block/part-007/block |
| 060 16G fuchsia-fvm fuchsia-fvm /dev/sys/pci/00:17.0/ahci/sata2/block/part-008/block |
| </span> |
| </pre> |
| |
| 1. Install the ESP to the disk. Note that the "ID" column in lsblk |
| corresponds to a file in /dev/class/block/<ID>. You should replace |
| `002` with the ID of the partition that's labelled `efi`, and `052` |
| with the ID of the partition that's labelled `efi-system`. |
| |
| |
| <pre class="prettyprint"> |
| <code class="devsite-terminal">dd if=/dev/class/block/<var>002</var> of=/dev/class/block/<var>052</var></code> |
| <span class="no-select"> |
| 2194+0 records in |
| 2194+0 records out |
| 1123328 bytes copied |
| </span> |
| </pre> |
| |
| 1. Install the main kernel image. Replace `003` with the ID of the partition on |
| the USB drive labelled `zircon-a`. |
| |
| Note: A limitation in the block device protocol means we need |
| to `dd` to an intermediary file before using `install-disk-image`. |
| |
| <pre class="prettyprint"> |
| <code class="devsite-terminal">dd if=/dev/class/block/<var>003</var> of=/tmp/tmp.img</code> |
| <span class="no-select"> |
| 52520+0 records in |
| 52520+0 records out |
| 26890240 bytes copied |
| </span> |
| <code class="devsite-terminal">install-disk-image install-zircona --file /tmp/tmp.img</code> |
| <span class="no-select"> |
| disk-pave: install-zircona operation succeeded. |
| </span> |
| </pre> |
| |
| 1. Install the recovery kernel image. Replace `004` with the ID of the partition |
| on the USB drive labelled `zircon-r`. |
| |
| <pre class="prettyprint"> |
| <code class="devsite-terminal">dd if=/dev/class/block/<var>004</var> of=/tmp/tmp.img</code> |
| <span class="no-select"> |
| 52520+0 records in |
| 52520+0 records out |
| 26890240 bytes copied |
| <code class="devsite-terminal">install-disk-image install-zirconr --file /tmp/tmp.img</code> |
| <span class="no-select"> |
| disk-pave: install-zirconr operation succeeded. |
| </span> |
| </pre> |
| |
| 1. Install the Fuchsia volume image. Replace `005` with the ID of the partition |
| on the USB drive labelled `storage-sparse`. |
| |
| Note: this image is much bigger than any of the others - this step |
| may take a while! |
| |
| <pre class="prettyprint"> |
| <code class="devsite-terminal">dd if=/dev/class/block/<var>005</var> of=/tmp/tmp.img</code> |
| <span class="no-select"> |
| 658432+0 records in |
| 658432+0 records out |
| 337117184 bytes copied |
| </span> |
| <code class="devsite-terminal">install-disk-image install-fvm --file /tmp/tmp.img</code> |
| <span class="no-select"> |
| disk-pave: install-fvm operation succeeded. |
| </span> |
| </pre> |
| |
| 1. Unplug the installation USB drive. |
| |
| 1. Reboot your machine. |
| |
| <pre class="prettyprint"> |
| <code class="devsite-terminal">dm reboot</code> |
| </pre> |
| |
