ISO/USB Script (MicroInstall OS) Example/ Micro Tutorial.

[MultimediaMan]

On an earlier thread, a Forum member was attempting to build something I had already built sometime ago for Networks (or Hardware) which might not have DHCP or PXE configured. This embedded script is fairly comprehensive and will help Sysadmins with one-off systems and/or legacy networks leverage iPXE.

Broadly, the script enables the img/ISO to attempt to DHCP three times, and failing that, drop to an interactive menu for the user to input the Host/Network Information manually, hopefully getting onto the network.

Once on the network, the embedded script will attempt to reach the webserver defined by the user or in the ${17} variable for further commands using a number of schemes (UUID, Hostname, MAC address and then a default.ipxe) before failing out.

There are a good number of variable tests placed into the script to programmatically obtain, utilize and display information about a given booted host, allowing the Sysadmin a fair degree of flexibility in controlling the host both locally (and with the correct backend, remotely).

Assumptions: A webserver with a directory structure of ${17}/NetBoot/iPXE/ipxelinux.cfg/

With subdirectories of "uuid", "dns", "net" with all files contained being ${VariableType}.ipxe

e.g. for /net; 01-${HypenatedMACAddr}.ipxe

Also with a subdirectory and file of "default/default.ipxe"

Code:

#!ipxe
#Embedded Boot Script 4 ISO/USB/Disk-based iPXE
#loc: /dev/sdx
#Zer0 Stratum; all Variables should be prefaced with a "0_"

set emb_eph 1.0.0+ (12345) ; set esc:hex 1b ; set cls ${esc:string}[2J ; set 0_lp:int32 0 ; inc 0_lp ; set 0_mode unk
cpuid --ext 29 && set arch x86_64 || set arch i386
cpuid 6 && set pae 1 || set pae 0
cpuid --ecx 5 && set vmx 1 || set vmx 0
cpuid --ext --ecx 2 && set svm 1 || set svm 0
iseq ${net0/chip} undi && set 0_mode UNDI ||
iseq ${net0/chip} NII && set 0_mode SNP ||
iseq ${0_mode} unk && set 0_mode Native ||
echo ; echo iPXE is in ${platform} ${0_mode} Mode... ; echo

:0_retry echo DHCP Attempt ${0_lp} ; dhcp net0 || inc 0_lp
isset ${net0/gateway} && goto 0_dns || goto 0_usrnpu
iseq ${0_lp} 4 && goto 0_usrnpu || sleep 2 ; goto 0_retry

:0_usrnpu ; echo DHCP Failed; Please enter the following information:
echo -n Enter Hostname: && read hostname
echo -n IP Address: && read net0/ip
echo -n Subnet Mask: && read net0/netmask
echo -n Default Route: && read net0/gateway
ifopen net0

echo -n DNS Server: && read net0/dns
echo -n DNS Suffix: && read 15
isset ${17} && goto 0_dns ||
echo -n Root Path: && read 17

:0_dns isset ${hostname} || set hostname DHCP-${net0/mac:hexhyp}
#Adding line below to compensate for Microsoft DHCP servers
iseq ${hostname} UnkownName && set hostname DHCP-${net0/mac:hexhyp} ||
isset ${130} || goto 0_sysnfo
set base-iqn ${130} ; isset ${base-iqn} && set initiator-iqn ${base-iqn}:${hostname}.${15} ||

:0_sysnfo echo ; echo iPXE System Summary: ; echo Embedded Script: ${emb_eph}, NBP: ${version}
echo Processor Type: ${arch}, PAE Support: ${pae}
iseq ${vmx} 1 && echo VTx Support ${vmx} ||
iseq ${svm} 1 && echo AMD-v Support ${svm} ||
echo Hostname: ${hostname} ; isset ${dnssl} && echo DNS Search Order: ${dnssl} ||
isset ${130} && echo IQN: ${initiator-iqn} ||
echo Model: ${product} ; echo UUID: ${uuid}
echo SN#: ${serial} ; echo Boot NIC MAC Address: ${net0/mac}, NIC Driver: ${chip} ; echo Root Path: ${17} ; echo Boot Filename: ${filename} ; echo ; sleep 5

echo ${cls}

:0_str set 0_menu-option 0_str
menu iPXE menu for ${hostname}.${15}
item --gap --    ------------------------- ${platform} ${0_mode} iPXE Stack -------------------------
item --key a    0_a_str Auto Start Deployment
item --key s    0_she    iPXE Shell
item --key e    0_end    Exit iPXE
choose --timeout 5000 --default 0_a_str selected ||
set menu-timeout 0 ; goto ${selected}
:0_she shell
goto 0_str

:0_a_str
chain ${17}/NetBoot/iPXE/ipxelinux.cfg/uuid/${uuid}.ipxe || echo ${cls}
chain ${17}/NetBoot/iPXE/ipxelinux.cfg/dns/${hostname}.ipxe || echo ${cls}
chain ${17}/NetBoot/iPXE/ipxelinux.cfg/net/01-${net0/mac:hexhyp}.ipxe || echo ${cls}
chain ${17}/NetBoot/iPXE/ipxelinux.cfg/default/default.ipxe || echo ${cls}
goto 0_str

:0_end ; echo ; echo Thank You for using iPXE! ; sleep 3 ; exit

Notes: I prefer to start embedded script variables with "0_" and Web Hosted scripts with a "1_" and progressing after that, depending on how the backend setup is configured.

There are some other unique variables which could be used which I have purposely omitted: ${asset} (Dell systems rely on this entry) and ${serial} (notionally the Serial Number of the system), but the implementation by other vendors is haphazard.

Use caution when using a MAC address as a unique identifier: In today's virtualized environments, these addresses can change or (in large environments) be duplicated, and you can have a devil of a time sorting it all out.

My favorite unique variable is the UUID, and it is not without it's foibles: The BIOS, OS and iPXE may not agree on how to display this variable (older systems, particularly consumer-grade motherboards, may not have a truly unique UUID). There are bit shifting schemes you can use to compensate for "Endian-ness" which aren't too complicated to implement and maintain.

Resourceful administrators will embed/write unique values in whichever "uuid", "dns", "net" file/ entry applies to a particular host and have various scripts/ processes refer to that.

Experienced administrators will write the backend processes (in Ansible/CHEF/Ironic or good old PHP or even BASH) to where even "unknown" systems can be automatically discovered, recorded when using the ISO (or PXE) and will have generic entries written into the Webserver by a backend process for future use.