====== Embedded scripts ======

You can change the default behaviour of iPXE by using an embedded [[:scripting|script]].  For example, you could embed the script:

    #!ipxe
    
    dhcp
    chain http://bootserver/boot.php

This script would cause iPXE to use DHCP to obtain an IP address and then boot from the fixed URL ''%%http://bootserver/boot.php%%'' (ignoring any boot filename provided by DHCP).  This can be useful if you are unable to reconfigure your DHCP server to provide an appropriate boot filename.

There are several methods that you can use to embed a script within iPXE.

{{ :clipart:bootroms.jpeg?350x190|Some PXE ROMs}}

===== Embedding within the iPXE binary =====

You can embed a script within the iPXE binary when you [[:download|build]] iPXE using the ''%%EMBED=...%%'' build parameter.  For example, to embed a script saved as ''myscript.ipxe'' into a [[:howto:chainloading|chainloadable]] iPXE image:

    make bin/undionly.kpxe EMBED=myscript.ipxe

This will create a custom version of the iPXE binary ''undionly.kpxe'' which includes your embedded script.

This method works with all iPXE binary formats (''.rom'', ''.iso'', ''.kpxe'' and so on).  To change the embedded script, you would need to rebuild the iPXE binary.

===== Embedding via the command line =====

You can embed a script by passing in a command line to iPXE.  For example, to embed a script into an iPXE image loaded by [[http://www.gnu.org/software/grub/|GRUB]]:

    timeout 10
    default 0
    
    title iPXE
    kernel (hd0,0)/ipxe.lkrn dhcp && chain http://bootserver/boot.php

This uses a standard version of the iPXE binary ''ipxe.lkrn''.  You can change the embedded script simply by editing the GRUB configuration file, with no need to rebuild the iPXE binary.

This method works only with iPXE binary formats that support a command line, such as ''.lkrn''.

Note that you may need to escape some special characters to allow them to be passed through to iPXE.

{{ :clipart:disk.jpeg?240x186|A disk}}

===== Embedding via an initrd =====

You can embed a script by passing in an initrd to iPXE.  For example, to embed a script saved as ''myscript.ipxe'' into an iPXE image loaded by [[http://www.gnu.org/software/grub/|GRUB]]:

    timeout 10
    default 0
    
    title iPXE
    kernel (hd0,0)/ipxe.lkrn
    initrd myscript.ipxe

This uses a standard version of the iPXE binary ''ipxe.lkrn''.  The ''myscript.ipxe'' file is a plain iPXE script file; there is no need to use a tool such as ''mkinitrd''.

You can change the embedded script by editing the ''myscript.ipxe'' file, with no need to rebuild the iPXE binary.

This method works only with iPXE binary formats that support an initrd, such as ''.lkrn''.

===== The "Press Ctrl-B" prompt ===== 

When you embed a script, you will no longer see the "Press Ctrl-B for the iPXE command line" prompt at startup or if booting fails.((If you are using an iPXE ROM, then you will still see the initial "Press Ctrl-B to configure iPXE" prompt that appears during the power-on self-tests (POST).  If you want to disable this initial prompt, you can do so by editing the file ''config/general.h'' to include the line:<code>    #define BANNER_TIMEOUT 0</code>))

If you would like to provide the user an opportunity to access the iPXE command line, then you can provide your own replacement prompt using the ''[[:cmd:prompt]]'' command.  For example:

    prompt --key 0x02 --timeout 2000 Press Ctrl-B for the iPXE command line... && shell ||

{{ :clipart:bootrom.jpeg?120x96 |A boot ROM}}