iPXE README File (as adapted to illumos systems)

To build:

gmake install

ipxe, unlike virtually all other software, actually assumes and requires GNU ld to build. This is because of the presence of GNU linker scripts. These could be converted to ld, but there's little need; since this does not generate anything that actually runs under illumos, the GNU linker's deficiencies aren't especially important.

If your system is not SmartOS, or is older than 20121213, your 'awk' is most likely 'oawk', which will hang on a construct used by the makefiles. Use nawk or gawk instead.

The build system uses grep -E, supported by the XPG4 grep but not the Sun one. You can also use GNU grep if necessary.

You will need gcc and GNU binutils installed from pkgsrc or some similar repository of packages, or to have built your own. Version requirements are very broad and almost anything should suffice.

You may need to obtain and install syslinux, which does build on illumos systems. This utility is used by util/genliso and util/gensdsk. You will need to determine whether your use case requires these utilities.

For any more detailed instructions, see http://ipxe.org

Updating

Occasionally we'll want to sync with upstream, e.g., to pick up nic card driver updates. This documents that process.

1. First you need an issue ID either in Jira or github for the sync up.

2. Add a remote for the upstream ipxe repo if you don't already have one.

    git remote add upstream https://github.com/ipxe/ipxe
   

3. Add a remote tracking branch for the upstream repo and fetch their changes.

    git checkout -b upstream upstream/master
    git fetch upstream
   

4. Create a branch for the issue and merge from upstream.

    git checkout -b <ISSUE_ID>
    git merge upstream
   

   Change the commit message to reflect the Triton commit message format.

5. Push the issue branch.

    git push -u origin HEAD:<branchname>
   

   Jenkins will automatically create a build for you and push the build artifacts to Manta and the experimental channel on updates.tritondatacenter.com.

6. Once the jenkins build is done you'll need to update sdc-booter, so cd to wherever you have a clone of that repo.

    cd <wherever you keep your repos>/sdc-booter
   

7. Again, create a branch for the issue.

    git checkout -b <ISSUE_ID>
   

8. Use the update_ipxe script. This will update tftpboot/snponly.efi and tfptboot/undionly.kpxe. Again, commit the changes and push the branch up.

    ./tools/update_ipxe <ISSUE_ID>
    git add tftpboot
    git commit
    git push -u origin HEAD:<branchname>
   

   And again, Jenkins will automatically create a build and push it to the experimental channel.

   Note: You need to have write permission to TritonDataCenter's repo(s) for this step. If you're an outside contributor push it to your own fork and open a pull request.

You're done. After testing, get code review, integration approval, then update the merge commit message and commit.

Note about merging: Github does not allow fast-forward merges so do not use the Github pull request's green button to bring in your upstream merge. Github MUST add a merge commit on top of your merge-from-upstream merge commit, never mind any post-merge adjustment commits you may need to make. Regardless, once approved via github PR review, you should, in your ipxe repo:

git checkout master
git merge <ISSUE_ID>

if it does NOT say "fast-forward", you will need to start over from the updated master branch in our ipxe. Here is what it should look like:

	smartos-build(~/ipxe)[0]% git merge TRITON-2354
	Updating 1522fe85..c7814698
	Fast-forward
	smartos-build(~/ipxe)[0]% 

Finally update the merge message with the ISSUE_ID, and a list of commits from upstream. To obtain list, first find the LAST upstream commit you merged priot to this one. Call it LAST_COMMIT. Then:

git log --format=oneline $LAST_COMMIT.. | awk '{print "commit " $1 ; $1 = "" ; print "   " $0}' > /tmp/list

The output in /tmp/list should appear in the merge commit below the issue. The above example looks a bit like this:

commit c7814698ae41c5247750b3a54e29c0c83601fc9d
Merge: 1522fe85 3fe683eb
Author: Dan McDonald <[email protected]>
Date:   Wed Dec 7 10:59:10 2022 -0500

    TRITON-2354 Merge properly with ipxe/ipxe to restore merge-commit path.
    
    commit 3fe683ebab29afacf224e6b0921f6329bebcdca7
        [lan78xx] Always enable automatic speed and duplex detection
    commit 41a9a5c7b3674f0fac6d8fa3b633cde17c2df78f
        [efi] Do not attempt EFI_USB_IO_PROTOCOL transfers during shutdown
    <MORE COMMITS not shown here...

And the "3fe684eb..." commit will be used for LAST_COMMIT on your NEXT upstream merge.

Once the message is updated, then you can use "git push" from the command line. Github WILL be smart enough to close your PR.

Testing changes

Warning: If there's a problem with the boot files the compute node(s) may not be able to boot at all. It is recomended to perform testing on hardware that you can access physically, or can withstand being down for an extended period of time in case something goes wrong.

You'll need to test this on as many different hardware platforms and as many different configurations as you can, including virtualized hardware such as VMware, Linux KVM, and BHYVE. In particular, the following configurations need to be tested.

• Booting from the USB in EFI mode
• Booting from the USB in legacy mode
• PXE booting from the hardware NIC and chain loading ipxe over the network in EFI mode
• PXE booting from the hardware NIC and chain loading ipxe over the network in legacy mode
• VMware (using images from https://github.com/TritonDataCenter/sdc-headnode/tree/master/vmware) which will chain load iPXE from booter.

To install the new ipxe files on an existing Triton USB, download the ipxe build either from Manta or updates.tritondatacenter.com. Extract the tar and copy the contents of the extracted boot directory to the boot directory on the USB, overwriting the existing files.