Configuration settings

iPXE provides access to a variety of configuration settings. You can browse and edit these settings interactively using the interactive configuration tool:

You can also access these settings from the command line or from within an iPXE script. For example, you can display the current 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 UUID:

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

You can create your own user interface to edit a selection of settings interactively using the present command:

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

The easiest way to explore the hierarchy is to use the interactive configuration tool. You can also use the set, show, and 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 priority setting can be used to determine precedence between scopes at the same level of the hierarchy.

Each configuration setting has an associated type. For example, the boot filename has the type string, and the IPv4 default gateway address has the type ipv4.

You can observe the type of a setting using the 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 hex:

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

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

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 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