Bug 871565 - Need a section in the install guide regarding pxe booting on UEFI systems
Summary: Need a section in the install guide regarding pxe booting on UEFI systems
Alias: None
Product: Fedora Documentation
Classification: Fedora
Component: install-guide
Version: devel
Hardware: Unspecified
OS: Unspecified
Target Milestone: ---
Assignee: Petr Bokoc
QA Contact: Ruediger Landmann
Depends On:
Blocks: 891467
TreeView+ depends on / blocked
Reported: 2012-10-30 17:49 UTC by Neil Horman
Modified: 2013-07-31 14:40 UTC (History)
3 users (show)

Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Clone Of:
: 891467 (view as bug list)
Last Closed: 2013-07-31 14:40:32 UTC

Attachments (Terms of Use)
sample dhcpd6.conf file (2.08 KB, application/octet-stream)
2012-12-19 14:49 UTC, Neil Horman
no flags Details

Description Neil Horman 2012-10-30 17:49:30 UTC
Description of problem:
Fedora 18 will see greater use of UEFI systems, and as such we should round out our documentation regarding how to boot UEFI systems via other common methods besides those already addressed.  Most notably the use of pxe boot in UEFI environments will now be available with secure boot enabled via both ipv4 and ipv6 the by using shim layer code:

We should further document how to boot a system and setup a pxe server to allow booting UEFI systems in this manner

Comment 1 Jack Reed 2012-11-12 06:01:52 UTC
Thanks Neil.

Are you able to give me some details on how the procedure for setting up a PXE server for EFI would need to be changed to account for this?


And I expect the "Booting from the Network using PXE" section needs to be tweaked to account for EFI as well:


Are you able to tell me how this process differs on EFI systems? 

And what else would you like included here or elsewhere, particularly with regard to secure boot being enabled via via both ipv4 and ipv6 the by using shim layer code? I'm unclear on how this affects the procedure/s.

And what are the other common methods that are not addressed that you would like to see covered?

Comment 2 Neil Horman 2012-12-18 16:19:16 UTC
I'm sorry, the description above isn't complete.  The additional need for documentation here is not exclusively to support UEFI systems, but to support them using PXE for IPV4 and IPV6 using non secureboot and secureboot environments.  The documentation you have covers IPV4 in a non-secureboot environment.  I'll try to touch on the general changes that need to be made in each case:

PXE+UEFI+IPV4+NO Secureboot - You're good to go, no changes need to be made

PXE+UEFI+IPV6+No Secureboot - the server dhcp6 option is not filename, you need to instead specify bootfile-url option, which is a text string of the form:

PXE+UEFI+[IPv4|IPV6]+Secureboot - You can't boot grub directly with secureboot enabled, as its unsigned.  We're in the process of getting the shim utility:
It will be signed and needs to be specified as the filename option or the bootfile-url option on the dhcp server.  The shim utility will be downloaded, validated, and then it will be responsible for downloading the actual grub image (which must be named grub.efi or grubx64.efi and be tftp-able from the same location that the shim image was located at)

So, I'm not sure at how you're looking to organize the docs for fedora (if you want to document secureboot booting procedures separately from non-secureboot environments or not), but thats the information that I was hoping to cover in this bz.  If you feel like you have all that information in various locations, and can ennumerate them here, I think that would satisfy this bz in my mind.  If any of it is missing however, and can be added, I would greatly appreciate it.  I've got some virtual qemu guests setup to run an IPv6+UEFI+secure boot emulated environment here which you're welcome to poke around with to help flesh out the instructions if need be.  And of course, I'm happy to answer any further quesstions you might have here.


Comment 3 Jack Reed 2012-12-19 05:31:51 UTC
Thanks for this, Neil. Having the distinct requirements for each use case outlined is really useful.

However, I'm still not clear on the context or exact format of these configuration changes. Are they made in /etc/dhcp/dhcpd.conf, a sample of which is provided in step 4 of the following?


If so, I assume that 'filename "pxelinux/bootia32.efi";' should be replaced with 'bootfile-url="tftp://[ipv6-address-in-brackets]/path/to/grub.efi' (in the second use case you outline) or whatever is required for the third use case. Is that correct?

But the config file in step 4 is only an example, and the filename strings in it are relevant in case certain conditions are met, whereas the filename and bootname-url strings you're referring to are perhaps uniform rather than conditional.

Would you mind providing quick edited versions of that sample config file that incorporate these IPv6 and IPv4/6 Secureboot strings? (I'm particularly unclear on how to configure the latter.) Assuming that's where the editing needs to be done, of course.

If it is, then explaining what is needed for IPv6 and SecureBoot in the 'Configuring for EFI' procedure may be enough, as opposed to breaking them off into another procedure. If the steps prove too difficult to integrate though, I will break them off.

That said, you might be interested in an F18 draft document I've just been reminded of: http://docs.fedoraproject.org/en-US/Fedora_Draft_Documentation/0.1/html-single/UEFI_Secure_Boot_Guide/index.html

It's only in the early stages, but the material you want to add may also be beneficial here. Or you may feel that it is best suited to that guide alone. I don't have the perspective on the applicability of this new material to gauge that, so let me know what you think.

Comment 4 Neil Horman 2012-12-19 14:11:43 UTC
Sure, I'll attach my sample configs in a bit.

To answer your specific questions above:

1) When configuring pxe for IPv6 vs. IPv4, the dhcp server configuration needs to change.  Specifially, when using ipv4 you need to specify the filename dhcp option, exactly as it appears in the current netboot document you reference above

When configuring pxe for ipv6 (weather or not you use secure boot, or UEFI for that matter), in addition to modifying the dhcp server configuration to serve ipv6 addresses, pxe support requires that you, instead of using the filename dhcp option to specify the file to download, you instead use the bootfile-url option, which is formatted as I noted above (its also expanded on in the dhcp-options man page).

Note this change is orthogonal to any changes required to enable secureboot over pxe.  This is just the change needed to support ipv6 pxe boot.  As you not above, your configuration example is just that, an example.  I don't know if you want to expand on it to demonstrate how pxe works differently with ipv6.  If you do however (and I think it would be a good idea), the bootfile-url option is what you need to document.

2) Secureboot, when enabling secureboot, you have to make some additional changes.  Specifically you have to specify a special file to download (not just the grub bootloader).  This is because grub won't be signed with the master key.  The shim utility I mentioned before will.  If you're trying to boot a system via pxe in UEFI secure boot mode using ipv4, you have to use the filename dhcp option to specify that the shim utilty file be downloaded, whereas if you are booting a system via pxe in UEFI secure boot mode over ipv6, then you need to specify the shim utilty file on the dhcp server using the bootfile-url option.  Note that if you are _not_ in secure boot mode, then you can specify any pxe boot file that you want on the server.  Thats the meat of the change here: When in secure boot mode you need to specify the shim utilty as the file to download via tftp, as opposed to operating in non-secure-boot mode, when you can download and run any arbitrary file.

Looking at your Secure boot page, I think thats a good start.  Perhaps thats how this documentation should be split up - item (1) above can be edited into the netboot documentation, to show how the dhcp server config changes when using ipv6, and item (2) can be discussed in the secure boot page (since the shim utiltiy is requried when using secure boot, regardless of weather your booting locally or via pxe).

I'll attach my sample dhcpd6.conf file in just a moment.

Comment 5 Neil Horman 2012-12-19 14:49:06 UTC
Created attachment 666108 [details]
sample dhcpd6.conf file

Heres my example dhcpd6.conf file, which uses the bootfile-url option.  Note that it specifies the shim.efi utility.  This setup was used to boot a system in secure boot mode. If we weren't in secure boot mode, we could download any file we wanted.  As it is, the shim utility is signed, alowing it to be run in secure boot mode.  Once its validated, it will attempt to download the grubx[32|64].efi file from the same location it was downloaded from.

Comment 6 Jack Reed 2013-01-04 02:22:03 UTC
Terrific, thanks Neil.

I've discussed this with two of the authors of the Secure Boot Guide and we've decided that the Secureboot material will be covered in that guide (which you concurred with by email). I've cloned this bug against that guide (see bug 891467).

That leaves the extra information for configuring PXE for IPv6. I've added another config file example to step 4 of the procedure (see link in Comment 3) using the sample you've provided, and explained that the bootfile-url string should be used instead of the filename option.

See http://git.fedorahosted.org/cgit/docs/install-guide.git/commit/?id=4e36aa4ea4b356899051da13349f6c72573fd3b3

Now that the Secureboot material is being addressed in the cloned bug, this bug is now resolved.

Comment 7 Jack Reed 2013-01-11 02:42:50 UTC
After closer consideration of the Secureboot material, I've decided that due to its brevity it makes sense to include it in the Installation Guide procedure for configuring PXE for EFI. The Secure Boot Guide can instead refer readers to that procedure.

The commit for this addition is here: http://git.fedorahosted.org/cgit/docs/install-guide.git/commit/?id=5ab81ed1779ed2520747979ec38aa95f426ed63e

I will close bug 891467, the clone of this bug for the Secure Boot Guide.

Note You need to log in before you can comment on or make changes to this bug.