====== Boot from SAN device ======

===== Synopsis =====

    sanboot [--drive <drive>] [--filename <filename>] [--extra <filename>]
            [--label <label>] [--uuid <uuid>]
            [--no-describe] [--keep] [<uri>] [<uri>...]

===== Examples =====

=== Boot from an iSCSI target ===

    sanboot iscsi:10.0.4.1:::1:iqn.2010-04.org.ipxe.dolphin:storage

=== Boot from a multipath iSCSI target ===

    sanboot iscsi:192.168.0.101::::iqn.2010-04.org.ipxe.squirrel:storage \
            iscsi:192.168.0.102::::iqn.2010-04.org.ipxe.squirrel:storage

=== Boot from an iSCSI target with a non-default filename ===

    sanboot --filename \EFI\redhat\grub.efi \
            iscsi:192.168.0.2::::iqn.2010-04.org.ipxe.chipmunk:rhel6

=== Boot from an HTTP target ===

    sanboot http://boot.ipxe.org/freedos/fdfullcd.iso

=== Boot from local drive 0x80 ===

    sanboot --no-describe --drive 0x80

=== Attach a SAN target and then boot an installer held on another target ===

    sanhook --drive 0x81 ${root-path}
    sanboot --no-describe iscsi:10.0.4.1:::1:iqn.2010-04.org.ipxe.dolphin:liveinstall

===== Description =====

Boot from the specified SAN drive.  If no SAN drive is explicitly specified then the default SAN drive (''%%0x80%%'') will be used.  If one or more [[:sanuri|SAN target URIs]] are specified then they will be automatically attached as the specified SAN drive.

The SAN drive will be described via an appropriate mechanism (such as an iBFT for an iSCSI drive) unless the ''%%--no-describe%%'' option is specified.

On some platforms (e.g. UEFI), additional options may be used to control the SAN boot:

  * If the ''%%--filename%%'' option is specified, then only a partition containing the specified filename will be selected as the boot partition, and the specified filename will be used as the bootloader within the SAN drive.
  * If the ''%%--extra%%'' option is specified, then only a partition containing the specified additional filename will be selected as the boot partition. 
  * If the ''%%--label%%'' option is specified, then only a partition with the specified (case-insensitive) volume label will be selected as the boot partition.
  * If the ''%%--uuuid%%'' option is specified, then only a partition with the specified GPT partition GUID will be selected as the boot partition.

===== Command status =====

^ Failure   | Booting was unsuccessful  |

It is generally impossible for this command to return successfully, since if the boot is successful then control will not return to iPXE. 

===== See also =====

  * ''[[:cmd:autoboot]]''
  * ''[[:cmd:sanhook]]''
  * ''[[:cmd:sanunhook]]''
  * [[:cmd|List of all iPXE commands]]

===== Notes =====

The BIOS Master Boot Record (MBR) code present on most SAN targets will be unable to boot unless the target is attached as the default SAN drive (''%%0x80%%'').

You can optionally specify a [[:sanuri|SAN target URI]] that will be automatically attached as the specified SAN drive before booting is attempted.  This drive will be automatically detached if booting then fails, unless the ''%%--keep%%'' option is specified.

You can create a multipath SAN device by specifying multiple SAN target URIs.  iPXE will use whichever SAN target responds first, and will retry all URIs if the original SAN target fails for any reason.  You must ensure that all SAN URIs in a multipath SAN device point to the same underlying SAN drive.

If you wish to attach to multiple independent SAN drives, then you must use the ''[[:cmd:sanhook]]'' command to attach each non-boot drive individually.

On a UEFI platform, some older operating systems (e.g. RHEL6) will install the bootloader with a non-default filename.  You can use the ''%%--filename%%'' option (or the ''[[:cfg:san-filename]]'' setting) to specify the correct bootloader filename.  For example:

    # For RHEL6
    sanboot --filename \EFI\redhat\grub.efi \
            iscsi:192.168.0.2::::iqn.2010-04.org.ipxe.chipmunk:rhel6
    
    # For Debian
    sanboot --filename \EFI\debian\grubx64.efi \
            iscsi:192.168.0.2::::iqn.2010-04.org.ipxe.chipmunk:debian10

For the sake of backwards compatibility, you can use the ''[[:cfg:keep-san]]'' setting to prevent iPXE from detaching a SAN drive, and you can use the ''[[:cfg:skip-san-boot]]'' setting to prevent iPXE from booting from a SAN drive.  The combination of both of these settings provides functionality which is approximately equivalent to the ''[[:cmd:sanhook]]'' command.

You can use the ''sanboot'' command to boot from a local disk drive without exiting iPXE.  This can be useful if BIOS or UEFI bugs prevent you from being able to cleanly exit iPXE.  For example:

    # Boot from local hard disk
    sanboot --no-describe --drive 0x80

On a UEFI platform you can specify drive number zero in order to boot from any matching disk (whether a SAN drive or local disk).  You can use this in conjunction with the filtering options ''%%--extra%%'', ''%%--label%%'', etc to boot from the correct disk without knowing its drive number.  For example:

    # Boot from any disk (SAN or local) containing a Fedora installation
    sanboot --drive 0 --extra \EFI\fedora