====== Download and boot an executable image ======

===== Synopsis =====

    chain [--name <name>] [--timeout <timeout>] [--autofree] [--replace]
          [<uri|image>] [<arguments>...]

or

    imgexec [--name <name>] [--timeout <timeout>] [--autofree] [--replace]
            [<uri|image>] [<arguments>...]

or

    boot [--name <name>] [--timeout <timeout>] [--autofree] [--replace]
         [<uri|image>] [<arguments>...]


===== Examples =====

=== Download and boot the iPXE demonstration image ===

    chain http://boot.ipxe.org/demo/boot.php

=== Download and boot pxelinux ===

    chain pxelinux.0

=== Download and boot a Linux kernel with an initrd and arguments ===

    initrd http://192.168.0.1/initrd.img
    chain http://192.168.0.1/vmlinuz vga=788 console=ttyS0,115200n8 console=tty0

=== Download, run, and automatically free a menu script ===

    chain --autofree http://10.0.0.1/scripts/menu.ipxe

=== Terminate the current script and run a new script ===

    chain --replace http://10.0.0.1/scripts/script.ipxe

=== Boot the currently-selected image ===

    boot

===== Description =====

Download and boot an executable image from the specified URI.  A name for the downloaded image can be specified using the ''%%--name%%'' option.  A download progress timeout can be specified (in milliseconds) using the ''%%--timeout%%'' option.  Any remaining arguments will be passed directly to the booted image.

If no image is explicitly specified, iPXE will boot the currently-selected image (as reported by the ''[[:cmd:imgstat]]'' command).

An image that has already been downloaded (e.g. by the ''[[:cmd:imgfetch]]'' command) can be specified by using the image's name instead of a URI.  For example:

    imgfetch http://192.168.0.1/vmlinuz
    boot vmlinuz

If this command is executed from within an iPXE [[:scripting|script]], then the URI will be interpreted as being relative to the URI of the script itself.  For example, if the script ''%%http://boot.ipxe.org/demo/boot.php%%'' contains the line

    chain pxelinux.0

then iPXE will download and boot ''%%http://boot.ipxe.org/demo/pxelinux.0%%''.

If the ''%%--autofree%%'' option is specified then the image will be freed automatically after terminating.  Otherwise, the image will remain present and can be freed using ''[[:cmd:imgfree]]''.


If the ''%%--replace%%'' option is specified then the image will replace the currently executing script (similar to the Unix ''exec()'' system call).  Otherwise, the current script will continue execution once the image returns.

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

^ Success   | The image was successfully downloaded and booted, and the image subsequently returned successfully |
^ Failure   | The image was not successfully downloaded and booted, or the image subsequently returned with an error |

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

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

  * ''[[:cmd:imgstat]]''
  * ''[[:cmd:imgfetch]]''
  * ''[[:cmd:kernel]]''
  * ''[[:cmd:imgfree]]''
  * [[:cmd|List of all iPXE commands]]

===== Notes =====

There is no difference between the commands ''chain'', ''imgexec'' and ''boot''.

If your script will exit immediately after the ''chain'' command then you can use the ''%%--replace%%'' option to minimise memory usage.

If you have a series of scripts that jump to each other and do not ever return (such as a menu system implemented as several separate iPXE script files) then you can use both ''%%--autofree%%'' and ''%%--replace%%'' to avoid running out of memory.

===== Backwards compatibility =====

In older versions of iPXE, you must use ''chain'' when you want to download and boot a new image from a URI, and you must use ''imgexec'' or ''boot'' when you want to boot an image that has already been downloaded.