docs/development/hardware/paving.md - fuchsia - Git at Google


            
            # Installing Fuchsia on a device


            This guide will help you understand the device installation process for Fuchsia.

            
            The Fuchsia install process, called 'paving', requires two machines, the machine

            
            on which you build Fuchsia ("host") and the device on which you want to run

            
            Fuchsia ("target"). The host and target must be able to communicate over a local

            
            area network.


            This guide covers at a high level how to use your host system

            
            to build Fuchsia, create a piece of install media, and stream

            
            the system over the network to the target.


            ## Building {#building}


            The `fx` command is used throughout these instructions. Before you can

            
            install Fuchsia on a device, you must have Fuchsia source on your host by

            
            following the instructions in these two documents:


             * [Fuchsia source installed and environment variables created](/docs/get-started/get_fuchsia_source.md).

            
             * [Configured and built Fuchsia](/docs/get-started/build_fuchsia.md)


            If you have `fx` mapped into your command path you can follow these instructions. If you

            
            don't have fx in your path, it can be found at `//scripts/fx` and you'll need

            
            to use the appropriate relative path in the supplied commands.


            Many `fx` commands are wrappers around build actions in [GN](/docs/concepts/build_system/intro.md)

            
            coupled with tool invocations.


            Assuming that the target system is x86-based and that you want to build a

            
            complete Fuchsia system, you can set Fuchsia with the following command:


            ```

            
            fx set {product_name}.x64`

            
            ```


            Note: For more information on supported products, see [product and board](/docs/concepts/build_system/boards_and_products.md).


            Then build Fuchsia:


            ```

            
            fx build

            
            ```


            ## Creating install media {#creating-install-media}


            To create your install media you should use a USB drive since these are

            
            well-supported as boot media by most systems.


            Note: Creating a USB drive **will wipe everything** from the USB drive being used.


            To create a USB drive, insert a USB drive into the target machine and run:


            ```

            
            fx mkzedboot <device_path>

            
            ```


            On Linux, `device_path` is typically `/dev/sd&lt;X&gt;` where X is a letter. On macOS

            
            it is typically `/dev/disk&lt;N&gt;` where 'N' is a number. **Be careful

            
            not to select the wrong device**. Once this is done, remove the USB drive.


            ## Paving {#paving}


            Next, you must build the artifacts to transfer over the network during the paving

            
            process. What is transferred is dependent on the target device. For UEFI based

            
            systems (like the Intel NUC) our output target type is 'efi'.


            To start the bootserver with the correct image just run `fx pave`.


            Insert the install media into the target device that you want to pave. The

            
            target device's boot settings may need to be changed to boot from the USB device

            
            and this is typically device-specific. For the guides listed below, **only** go

            
            through the steps to set the boot device, don't continue with any instructions

            
            on creating install media.


            * [Intel NUC](/docs/development/hardware/intel_nuc.md)


            Paving should occur automatically after the device is booted into Zedboot from

            
            the USB drive. After the paving process completes, the system should boot into

            
            the Zircon kernel. After paving, the whole system is installed on internal

            
            storage.


            At this point the USB key can be removed since the system has

            
            everything it needs stored locally. If you plan to re-pave frequently it may be

            
            useful to keep the USB drive inserted so your system boots into Zedboot by

            
            default where paving will happen automatically. After the initial pave on UEFI

            
            systems that use Gigaboot, another option for re-paving is to press 'z' while in

            
            Gigaboot to select Zedboot.


            ## Troubleshooting {#troubleshooting}


            In some cases paving may fail because you have a disk layout that is

            
            incompatible. In these cases you will see a message that asks you to run

            
            'install-disk-image wipe'. If it is incompatible because it contains an older

            
            Fuchsia layout put there by installer (vs the paver) you can fix this by killing

            
            the fx pave process on the host, switching to a different console (Alt+F3) on

            
            the target, and running `install-disk-image wipe`. Then reboot the target,

            
            re-run `fx pave` on the host, and the pave should succeed.


            In some cases paving may fail with an error indicating "couldn't find space in

            
            gpt". In these cases (as long as you don't want to keep the other OS, i.e.

            
            Windows, parts) run `lsblk` and identify the partition that isn't your USB (it

            
            shouldn't have RE in the columns). Identify the number in the first column for

            
            your partition (likely to be either 000 or 003). Then, run:


            Note: `N` is the number you just identified.


            ```

            
            gpt Init /dev/class/block/N

            
            ```


            This clears all Windows partitions from the disk. Once this is done, reboot into

            
            zedboot and paving should work.


            ## Changing boot target (localboot, netboot, etc) default


            For EFI-based systems, it is possible to change the default boot option of the

            
            system paved on the target between local booting and Zedboot for network

            
            booting. By default the system boots locally with a 1-second delay in Gigaboot

            
            to allow you to select a different mode. To change this default to Zedboot,

            
            supply the `always_zedboot` argument when calling your set command, for example

            
            `fx set <goal> --args "always_zedboot=true"`.


            ## More information


             * [Creating a Fuchsia USB flash drive](/docs/development/hardware/usb_setup.md)

            
             * [Step-by-step build and pave guide](/docs/development/build/build_and_pave_quickstart.md)

            
             * [More information on fx workflows](/docs/development/build/fx.md)
	# Installing Fuchsia on a device

	This guide will help you understand the device installation process for Fuchsia.
	The Fuchsia install process, called 'paving', requires two machines, the machine
	on which you build Fuchsia ("host") and the device on which you want to run
	Fuchsia ("target"). The host and target must be able to communicate over a local
	area network.

	This guide covers at a high level how to use your host system
	to build Fuchsia, create a piece of install media, and stream
	the system over the network to the target.


	## Building {#building}

	The `fx` command is used throughout these instructions. Before you can
	install Fuchsia on a device, you must have Fuchsia source on your host by
	following the instructions in these two documents:

	* [Fuchsia source installed and environment variables created](/docs/get-started/get_fuchsia_source.md).
	* [Configured and built Fuchsia](/docs/get-started/build_fuchsia.md)

	If you have `fx` mapped into your command path you can follow these instructions. If you
	don't have fx in your path, it can be found at `//scripts/fx` and you'll need
	to use the appropriate relative path in the supplied commands.

	Many `fx` commands are wrappers around build actions in [GN](/docs/concepts/build_system/intro.md)
	coupled with tool invocations.

	Assuming that the target system is x86-based and that you want to build a
	complete Fuchsia system, you can set Fuchsia with the following command:

	```
	fx set {product_name}.x64`
	```

	Note: For more information on supported products, see [product and board](/docs/concepts/build_system/boards_and_products.md).

	Then build Fuchsia:

	```
	fx build
	```

	## Creating install media {#creating-install-media}

	To create your install media you should use a USB drive since these are
	well-supported as boot media by most systems.

	Note: Creating a USB drive will wipe everything from the USB drive being used.

	To create a USB drive, insert a USB drive into the target machine and run:

	```
	fx mkzedboot <device_path>
	```

	On Linux, `device_path` is typically `/dev/sd<X>` where X is a letter. On macOS
	it is typically `/dev/disk<N>` where 'N' is a number. **Be careful
	not to select the wrong device**. Once this is done, remove the USB drive.

	## Paving {#paving}

	Next, you must build the artifacts to transfer over the network during the paving
	process. What is transferred is dependent on the target device. For UEFI based
	systems (like the Intel NUC) our output target type is 'efi'.

	To start the bootserver with the correct image just run `fx pave`.

	Insert the install media into the target device that you want to pave. The
	target device's boot settings may need to be changed to boot from the USB device
	and this is typically device-specific. For the guides listed below, only go
	through the steps to set the boot device, don't continue with any instructions
	on creating install media.

	* [Intel NUC](/docs/development/hardware/intel_nuc.md)

	Paving should occur automatically after the device is booted into Zedboot from
	the USB drive. After the paving process completes, the system should boot into
	the Zircon kernel. After paving, the whole system is installed on internal
	storage.

	At this point the USB key can be removed since the system has
	everything it needs stored locally. If you plan to re-pave frequently it may be
	useful to keep the USB drive inserted so your system boots into Zedboot by
	default where paving will happen automatically. After the initial pave on UEFI
	systems that use Gigaboot, another option for re-paving is to press 'z' while in
	Gigaboot to select Zedboot.


	## Troubleshooting {#troubleshooting}

	In some cases paving may fail because you have a disk layout that is
	incompatible. In these cases you will see a message that asks you to run
	'install-disk-image wipe'. If it is incompatible because it contains an older
	Fuchsia layout put there by installer (vs the paver) you can fix this by killing
	the fx pave process on the host, switching to a different console (Alt+F3) on
	the target, and running `install-disk-image wipe`. Then reboot the target,
	re-run `fx pave` on the host, and the pave should succeed.

	In some cases paving may fail with an error indicating "couldn't find space in
	gpt". In these cases (as long as you don't want to keep the other OS, i.e.
	Windows, parts) run `lsblk` and identify the partition that isn't your USB (it
	shouldn't have RE in the columns). Identify the number in the first column for
	your partition (likely to be either 000 or 003). Then, run:

	Note: `N` is the number you just identified.

	```
	gpt Init /dev/class/block/N
	```

	This clears all Windows partitions from the disk. Once this is done, reboot into
	zedboot and paving should work.

	## Changing boot target (localboot, netboot, etc) default

	For EFI-based systems, it is possible to change the default boot option of the
	system paved on the target between local booting and Zedboot for network
	booting. By default the system boots locally with a 1-second delay in Gigaboot
	to allow you to select a different mode. To change this default to Zedboot,
	supply the `always_zedboot` argument when calling your set command, for example
	`fx set <goal> --args "always_zedboot=true"`.

	## More information

	* [Creating a Fuchsia USB flash drive](/docs/development/hardware/usb_setup.md)
	* [Step-by-step build and pave guide](/docs/development/build/build_and_pave_quickstart.md)
	* [More information on fx workflows](/docs/development/build/fx.md)