====== Configuration settings ======

iPXE provides access to a variety of [[:cfg|configuration settings]].  You can browse and edit these settings interactively using the [[:cmd:config|interactive configuration tool]]:

{{ :screenshots:config_ui.png?360x200 |The interactive configuration tool}}

You can also access these settings from the [[:cmdline|command line]] or from within an iPXE [[:scripting|script]].  For example, you can display the current [[:cfg:ip|IP address]] as obtained via DHCP:

    iPXE> show net0/ip
    net0.dhcp/ip:ipv4 = 10.0.0.103

or configure a static IP address:

    iPXE> set net0/ip 192.168.0.3
    iPXE> set net0/netmask 255.255.255.0
    iPXE> set net0/gateway 192.168.0.1
    iPXE> route
    net0: 192.168.0.3/255.255.255.0 gw 192.168.0.1

or download and boot an operating system based upon the system [[:cfg:uuid|UUID]]:

    #!ipxe
    
    chain http://192.168.0.1/boot.php?uuid=${uuid}

===== Scopes =====

Configuration settings are arranged in a logical hierarchy of settings scopes:

{{ :clipart:settings_hierarchy.png?415x219 |Settings hierarchy}}

The easiest way to explore the hierarchy is to use the [[:cmd:config|interactive configuration tool]].  You can also use the ''[[:cmd:set]]'', ''[[:cmd:show]]'', and ''[[:cmd:clear]]'' commands to explore the effects of changing settings at various levels of the hierarchy.

For example, suppose that you have obtained a boot filename via DHCP:

    iPXE> dhcp net0
    DHCP (net0 52:54:00:12:34:56).... ok
    iPXE> show filename
    net0.dhcp/filename:string = http://192.168.0.1/boot.php

You can override this boot filename by configuring an alternative boot filename in the top level settings scope:

    iPXE> set filename vmlinuz
    iPXE> show filename
    filename:string = vmlinuz

The original boot filename (''net0.dhcp/filename'') still exists, but is overridden by the filename set in the top level scope:

    iPXE> show net0.dhcp/filename
    net0.dhcp/filename:string = http://192.168.0.1/boot.php
    iPXE> show net0/filename
    net0.dhcp/filename:string = http://192.168.0.1/boot.php
    iPXE> show filename
    filename:string = vmlinuz

Settings configured in a parent scope will always take precedence over any equivalent settings configured in a child scope.  The ''[[:cfg:priority]]'' setting can be used to determine precedence between scopes at the same level of the hierarchy.

===== Types =====

Each configuration setting has an associated type.  For example, the boot [[:cfg:filename]] has the type ''[[:cfgtype:string]]'', and the IPv4 default gateway address has the type ''[[:cfgtype:ipv4]]''.

You can observe the type of a setting using the ''[[:cmd:show]]'' command:

    iPXE> show filename
    filename:string = vmlinuz

You can specify the type of a newly-created setting by including the type within the setting's name:

    iPXE> set myvar:ipv4 212.13.204.60
    iPXE> show myvar
    myvar:ipv4 = 212.13.204.60

Settings are stored internally as arrays of bytes.  You can observe the raw byte array by choosing to interpret the setting using the type ''[[:cfgtype:hex]]'':

    iPXE> show filename
    filename:string = vmlinuz
    iPXE> show filename:hex
    filename:hex = 76:6d:6c:69:6e:75:7a

===== Applicability =====

Some settings take effect only within a particular scope.  In particular, settings specific to a network device take effect only within the scope of that network device.  For example, to set the IP address for ''net0'' you must set a value for ''net0/ip'' rather than just ''ip'':

    iPXE> set net0/ip 192.168.0.100
    iPXE> route
    net0: 192.168.0.100/255.255.255.0

{{ :clipart:dragon.png?134x132 |Here be dragons}} 

===== Advanced topics =====

==== PXE NBPs ====

PXE NBPs such as Windows Deployment Service's ''wdsnbp.com'' or ''pxelinux.0'' will attempt to retrieve the contents of the various DHCP packets used by iPXE (via the ''PXENV_GET_CACHED_INFO'' API call).  For example, ''wdsnbp.com'' will examine these DHCP packets to determine which TFTP server address to use.

There are three packets that may be requested by the PXE NBP: ''DHCPDISCOVER'', ''DHCPACK'' and ''BINL''.  iPXE will construct packets for the PXE NBP based on a combination of the actual DHCP packets and settings provided by other means (such as the ''[[:cmd:set]]'' command).

The scoping rules for the PXE NBP packets are slightly different from the logical hierarchy of settings scopes used within iPXE:

  * For the DHCPACK packet, any settings within the network device scope (e.g. ''netX/next-server'') will override any top-level settings (e.g. ''next-server'').
  * For the BINL packet, any settings present in the ProxyDHCPACK (e.g. ''proxydhcp/next-server'') or in the Boot Server Reply (e.g. ''pxebs/next-server'') will override any top-level settings (e.g. ''next-server'').

If you need to manually pass specific settings to a PXE NBP, then in most cases you should set these within the network device scope.  For example, to manually set the TFTP server address and path used by ''wdsnbp.com'', you could use:

    set netX/next-server 192.168.1.2
    set netX/filename boot\x86\wdsnbp.com
    chain tftp://192.168.1.2/boot/x86/wdsnbp.com