[GH-ISSUE #1198] Filename not properly interpreted by TFTP

kerem commented

2026-03-01 18:37:00 +03:00

Owner

Originally created by @BloodBlight on GitHub (Feb 5, 2023).
Original GitHub issue: https://github.com/netbootxyz/netboot.xyz/issues/1198

Describe the bug
This is related to this discussion from a while back:
https://github.com/netbootxyz/netboot.xyz/discussions/1133

I have an older client is sending a file name to the TFTP server, but is not being properly decoded into Unicode. I am not sure if the TFTP server is from another project (and this should be posted there), so please feel free to re-direct me and I will post it there.

What I see in the logs:
2022-07-08 15:28:56 notice in.tftpd[88]: RRQ from 192.168.10.206 filename netboot.xyz.kpxe��

The last characters (�) is (U+FFFD), a Unicode character for "Replacement Character". As it is at the end of the string, there could be a few causes, but without knowing the code...

To Reproduce
Attempt to boot from PXE.

Expected behavior
Should download the file and start booting.

Additional context
This is an old board, but a good one (kinda like a raspberry Pi, years before they were a thing. I can't find the exact model, but it is basically a Jetway J7F4K1G5DS-LF, just a bit slower (1.2GHz).

Originally created by @BloodBlight on GitHub (Feb 5, 2023). Original GitHub issue: https://github.com/netbootxyz/netboot.xyz/issues/1198 **Describe the bug** This is related to this discussion from a while back: https://github.com/netbootxyz/netboot.xyz/discussions/1133 I have an older client is sending a file name to the TFTP server, but is not being properly decoded into Unicode. I am not sure if the TFTP server is from another project (and this should be posted there), so please feel free to re-direct me and I will post it there. What I see in the logs: ```2022-07-08 15:28:56 notice in.tftpd[88]: RRQ from 192.168.10.206 filename netboot.xyz.kpxe��``` The last characters (�) is (U+FFFD), a Unicode character for "Replacement Character". As it is at the end of the string, there could be a few causes, but without knowing the code... **To Reproduce** Attempt to boot from PXE. **Expected behavior** Should download the file and start booting. **Additional context** This is an old board, but a good one (kinda like a raspberry Pi, years before they were a thing. I can't find the exact model, but it is basically a Jetway J7F4K1G5DS-LF, just a bit slower (1.2GHz).

kerem

2026-03-01 18:37:00 +03:00

closed this issue
added the
bug
label

kerem commented

2026-03-01 18:37:01 +03:00

Author

Owner

@MartinLoeper commented on GitHub (Oct 18, 2023):

I am noticing the same for a Lenovo T460 laptop. I am getting the following hex dump on the wire: 6e 65 74 62 6f 6f 74 2e 78 79 7a 2e 65 66 69 ff 00. The ff byte before the nullbyte should not be there. Is this a bug in the uefi firmware or am I missing something?

@MartinLoeper commented on GitHub (Oct 18, 2023): I am noticing the same for a Lenovo T460 laptop. I am getting the following hex dump on the wire: 6e 65 74 62 6f 6f 74 2e 78 79 7a 2e 65 66 69 ff 00. The ff byte before the nullbyte should not be there. Is this a bug in the uefi firmware or am I missing something?

kerem commented

2026-03-01 18:37:01 +03:00

Author

Owner

@antonym commented on GitHub (Oct 19, 2023):

Not really sure if there's anything on my side I can do about it, using Proxmox VMs to my docker container running tftp it seems to pull up without issues:

2023-10-18 03:54:57 notice in.tftpd[85]: RRQ from 10.0.100.155 filename netboot.xyz.efi

Wonder if whatever is serving up the filename for DHCP is putting some characters on the file name? Where are you setting next-server and setting the filename from? Is there a common router that may be appending some characters to the filename?

I think I've seen some other scenarios where people have had extra characters added to their filename, it could be a bug in a common router you might be using as well:

https://www.reddit.com/r/linuxquestions/comments/4rwesw/tftpboot_invalid_character_in_requested_filename/

@antonym commented on GitHub (Oct 19, 2023): Not really sure if there's anything on my side I can do about it, using Proxmox VMs to my docker container running tftp it seems to pull up without issues: ``` 2023-10-18 03:54:57 notice in.tftpd[85]: RRQ from 10.0.100.155 filename netboot.xyz.efi ``` Wonder if whatever is serving up the filename for DHCP is putting some characters on the file name? Where are you setting next-server and setting the filename from? Is there a common router that may be appending some characters to the filename? I think I've seen some other scenarios where people have had extra characters added to their filename, it could be a bug in a common router you might be using as well: https://www.reddit.com/r/linuxquestions/comments/4rwesw/tftpboot_invalid_character_in_requested_filename/

kerem commented

2026-03-01 18:37:01 +03:00

Author

Owner

@BloodBlight commented on GitHub (Oct 19, 2023):

I can have two computers sitting next to each other, one works, the other doesn't. Same target. I will verify that though (might not be today) to make sure I am not full of it. So I am fairly sure it is something about the way the client is making the request.

DHCP Is being handled by a UniFi USG 3. Fairly basic config:
https://imgur.com/a/ZnOfpZw

No idea why Imgur is tagging it as mature... Ignore.

@BloodBlight commented on GitHub (Oct 19, 2023): I can have two computers sitting next to each other, one works, the other doesn't. Same target. I will verify that though (might not be today) to make sure I am not full of it. So I am fairly sure it is something about the way the client is making the request. DHCP Is being handled by a UniFi USG 3. Fairly basic config: https://imgur.com/a/ZnOfpZw No idea why Imgur is tagging it as mature... Ignore.

kerem commented

2026-03-01 18:37:01 +03:00

Author

Owner

@megapearl commented on GitHub (Jan 18, 2024):

Having the same problem here.

Client:

Intel UNDI, PXE-2.1 (build 082)
Copyright (C) 1997-2000 Intel Corporation

This Product is covered by one or more of the following patents:
US5,307,459, US5,434,872, US5,732,094, US6,570,884, US6,115,776 and
US6,327,625

Realtek PCI Express Gigabit Ethernet Controller Series v2.26 (090219)

CLIENT MAC ADDR: 90 FB A6 41 09 ED CUID: C996DEBD-1DF6-1E31-E57C-90FBA64109ED
CLIENT IP: 10.0.0.100
MASK: 255.255.255.0 DHCP IP: 10.0.0.1
CATEWAY IP: 10.0.0.1

TFTP .
PXE-T01: File not found
PXE-E3B: TFTP Error - File Not found
PSE-MOF: Exiting PXE ROM.
Reboot and Select proper Boot device or Insert Boot Media in selected Boot device and press a key

Server:

@megapearl commented on GitHub (Jan 18, 2024): Having the same problem here. Client: Intel UNDI, PXE-2.1 (build 082) Copyright (C) 1997-2000 Intel Corporation This Product is covered by one or more of the following patents: US5,307,459, US5,434,872, US5,732,094, US6,570,884, US6,115,776 and US6,327,625 Realtek PCI Express Gigabit Ethernet Controller Series v2.26 (090219) CLIENT MAC ADDR: 90 FB A6 41 09 ED CUID: C996DEBD-1DF6-1E31-E57C-90FBA64109ED CLIENT IP: 10.0.0.100 MASK: 255.255.255.0 DHCP IP: 10.0.0.1 CATEWAY IP: 10.0.0.1 TFTP . PXE-T01: File not found PXE-E3B: TFTP Error - File Not found PSE-MOF: Exiting PXE ROM. Reboot and Select proper Boot device or Insert Boot Media in selected Boot device and press a key Server: ![image](https://github.com/netbootxyz/netboot.xyz/assets/3420660/06b2ff24-be54-4498-afc3-2278001f2b9d)

kerem commented

2026-03-01 18:37:01 +03:00

Author

Owner

@BloodBlight commented on GitHub (Jan 18, 2024):

I am tempted to do a packet capture...

I have had multiple older systems have this issue now...

@BloodBlight commented on GitHub (Jan 18, 2024): I am tempted to do a packet capture... I have had multiple older systems have this issue now...

kerem commented

2026-03-01 18:37:01 +03:00

Author

Owner

@rudiservo commented on GitHub (Feb 28, 2024):

The issue is in the DHCP server passing the information to old nics
In my case if you have this option

option bootfile-name "netboot.xyz.kpxe";

the old nic will put some special chars on the end of it.

if you have the config has specified in the docs

you have something like this in the dhcp server

if exists user-class and ( option user-class = "iPXE" ) {
   filename "http://boot.netboot.xyz/menu.ipxe";
 } elsif option arch = encode-int ( 16, 16 ) {
   filename "http://boot.netboot.xyz/ipxe/netboot.xyz.efi";
   option vendor-class-identifier "HTTPClient";
 } elsif option arch = 00:07 {
   filename "netboot.xyz.efi";
 } else {
   filename "netboot.xyz.kpxe";
 }

so try to remove option boot-filename if you NIC is to old.

@rudiservo commented on GitHub (Feb 28, 2024): The issue is in the DHCP server passing the information to old nics In my case if you have this option `option bootfile-name "netboot.xyz.kpxe";` the old nic will put some special chars on the end of it. if you have the config has specified in the [docs](https://netboot.xyz/docs/docker) you have something like this in the dhcp server ``` if exists user-class and ( option user-class = "iPXE" ) { filename "http://boot.netboot.xyz/menu.ipxe"; } elsif option arch = encode-int ( 16, 16 ) { filename "http://boot.netboot.xyz/ipxe/netboot.xyz.efi"; option vendor-class-identifier "HTTPClient"; } elsif option arch = 00:07 { filename "netboot.xyz.efi"; } else { filename "netboot.xyz.kpxe"; } ``` so try to remove option boot-filename if you NIC is to old.

kerem commented

2026-03-01 18:37:01 +03:00

Author

Owner

@antonym commented on GitHub (Feb 28, 2024):

Let me know if dropping the option helps and we can get the knowledge base updated.

@antonym commented on GitHub (Feb 28, 2024): Let me know if dropping the option helps and we can get the knowledge base updated.

kerem commented

2026-03-01 18:37:01 +03:00

Author

Owner

@BloodBlight commented on GitHub (Feb 28, 2024):

I will test later tonight and let you know.

On Wed, Feb 28, 2024, 10:17 AM Antony Messerli @.***>
wrote:

Let me know if dropping the option helps and we can get the knowledge base
updated.

—
Reply to this email directly, view it on GitHub
https://github.com/netbootxyz/netboot.xyz/issues/1198#issuecomment-1969572381,
or unsubscribe
https://github.com/notifications/unsubscribe-auth/AA6FDTXBM3L4Y22R3G2NCG3YV5YEXAVCNFSM6AAAAAAUR5ZCFSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSNRZGU3TEMZYGE
.
You are receiving this because you authored the thread.Message ID:
@.***>

@BloodBlight commented on GitHub (Feb 28, 2024): I will test later tonight and let you know. On Wed, Feb 28, 2024, 10:17 AM Antony Messerli ***@***.***> wrote: > Let me know if dropping the option helps and we can get the knowledge base > updated. > > — > Reply to this email directly, view it on GitHub > <https://github.com/netbootxyz/netboot.xyz/issues/1198#issuecomment-1969572381>, > or unsubscribe > <https://github.com/notifications/unsubscribe-auth/AA6FDTXBM3L4Y22R3G2NCG3YV5YEXAVCNFSM6AAAAAAUR5ZCFSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSNRZGU3TEMZYGE> > . > You are receiving this because you authored the thread.Message ID: > ***@***.***> >

kerem commented

2026-03-01 18:37:01 +03:00

Author

Owner

@BloodBlight commented on GitHub (Mar 1, 2024):

So, I didn't fully read through the instructions at work the other day... I am using a UniFi device for my DHCP and can't deploy a config like that. I only get the option to include a host and a file name:
https://imgur.com/a/aYicWfO

Suggestions other than a rip and replace?

@BloodBlight commented on GitHub (Mar 1, 2024): So, I didn't fully read through the instructions at work the other day... I am using a UniFi device for my DHCP and can't deploy a config like that. I only get the option to include a host and a file name: https://imgur.com/a/aYicWfO Suggestions other than a rip and replace?

kerem commented

2026-03-01 18:37:01 +03:00

Author

Owner

@rudiservo commented on GitHub (Mar 1, 2024):

@BloodBlight does it work without TFTP server?
Unifi are great, except when you need to dig deep.
Can you ssh into the router?

@rudiservo commented on GitHub (Mar 1, 2024): @BloodBlight does it work without TFTP server? Unifi are great, except when you need to dig deep. Can you ssh into the router?

kerem commented

2026-03-01 18:37:01 +03:00

Author

Owner

@BloodBlight commented on GitHub (Mar 1, 2024):

Yeeeeesss... :) But I am not really comfortable editing their their config without the GUI's consent. That has a bad tendency to break things.

If they don't have the options, then they don't and I can work around that. Maybe have a "deployment" network that has it's own server.

I can test that with these boxes, but it will take a bit more time. Too many plates and not enough spoons to handle that one right away.

@BloodBlight commented on GitHub (Mar 1, 2024): Yeeeeesss... :) But I am not really comfortable editing their their config without the GUI's consent. That has a bad tendency to break things. If they don't have the options, then they don't and I can work around that. Maybe have a "deployment" network that has it's own server. I can test that with these boxes, but it will take a bit more time. Too many plates and not enough spoons to handle that one right away.

kerem commented

2026-03-01 18:37:01 +03:00

Author

Owner

@rudiservo commented on GitHub (Mar 1, 2024):

I feel your pain.
Yes test it with the boxes
because if it does you can put a support request for unifi and hopefully they will add more options to fix it in the router GUI.

@rudiservo commented on GitHub (Mar 1, 2024): I feel your pain. Yes test it with the boxes because if it does you can put a support request for unifi and hopefully they will add more options to fix it in the router GUI.

kerem commented

2026-03-01 18:37:01 +03:00

Author

Owner

@megapearl commented on GitHub (Mar 16, 2024):

The issue is in the DHCP server passing the information to old nics In my case if you have this option

option bootfile-name "netboot.xyz.kpxe";

the old nic will put some special chars on the end of it.

if you have the config has specified in the docs

you have something like this in the dhcp server
if exists user-class and ( option user-class = "iPXE" ) {
   filename "http://boot.netboot.xyz/menu.ipxe";
 } elsif option arch = encode-int ( 16, 16 ) {
   filename "http://boot.netboot.xyz/ipxe/netboot.xyz.efi";
   option vendor-class-identifier "HTTPClient";
 } elsif option arch = 00:07 {
   filename "netboot.xyz.efi";
 } else {
   filename "netboot.xyz.kpxe";
 }
so try to remove option boot-filename if you NIC is to old.

Tried to remove the boot-filename parameter, but then the iPXE client cannot find a bootfile and is not booting at all.
I got it working by replacing the DHCP server in pfSense 2.7.2-RELEASE from the new Kea one to the old isc-dhcp deprecated one.

Now booting old bios clients and new uefi clients.

@megapearl commented on GitHub (Mar 16, 2024): > The issue is in the DHCP server passing the information to old nics In my case if you have this option > > `option bootfile-name "netboot.xyz.kpxe";` > > the old nic will put some special chars on the end of it. > > if you have the config has specified in the [docs](https://netboot.xyz/docs/docker) > > you have something like this in the dhcp server > > ``` > if exists user-class and ( option user-class = "iPXE" ) { > filename "http://boot.netboot.xyz/menu.ipxe"; > } elsif option arch = encode-int ( 16, 16 ) { > filename "http://boot.netboot.xyz/ipxe/netboot.xyz.efi"; > option vendor-class-identifier "HTTPClient"; > } elsif option arch = 00:07 { > filename "netboot.xyz.efi"; > } else { > filename "netboot.xyz.kpxe"; > } > ``` > > so try to remove option boot-filename if you NIC is to old. Tried to remove the boot-filename parameter, but then the iPXE client cannot find a bootfile and is not booting at all. I got it working by replacing the DHCP server in pfSense 2.7.2-RELEASE from the new Kea one to the old isc-dhcp deprecated one. ![image](https://github.com/netbootxyz/netboot.xyz/assets/3420660/3c0a9afe-0fac-4d99-b57e-41f48b3d785e) Now booting old bios clients and new uefi clients.

kerem commented

2026-03-01 18:37:02 +03:00

Author

Owner

@rudiservo commented on GitHub (Mar 16, 2024):

@megapearl I have OpnSense so the way PfSense and OpnSense generate the config file may be different, best way to check this is by going strait into ssh and cat the config file to check if the option is there.

Anyway it's good to know that at least in Kea generated file that issue is sort of mitigated.

IMO advisory should be added to docs about this issue and that it may differ from router firmware or software.

@rudiservo commented on GitHub (Mar 16, 2024): @megapearl I have OpnSense so the way PfSense and OpnSense generate the config file may be different, best way to check this is by going strait into ssh and cat the config file to check if the option is there. Anyway it's good to know that at least in Kea generated file that issue is sort of mitigated. IMO advisory should be added to docs about this issue and that it may differ from router firmware or software.

kerem commented

2026-03-01 18:37:02 +03:00

Author

Owner

@eladiogalvez commented on GitHub (May 12, 2024):

Same issue with pfsense and old nic.
Fixed using deprecated dhcp server as @megapearl commented.

@eladiogalvez commented on GitHub (May 12, 2024): Same issue with pfsense and old nic. Fixed using deprecated dhcp server as @megapearl commented.

kerem commented

2026-03-01 18:37:02 +03:00

Author

Owner

@gbuloz commented on GitHub (May 27, 2025):

Same issue with kea 2.6.2 on Fedora 41 when booting a 10 years old Kontron VX3040 Intel CPU board. After some debug with tcpdump I noticed an extra FF at the end of the filename requested to the TFTP server. As a workaround I've renamed the boot files on the server with an extra FF at the end of their names using : mv name.efi $(echo -en 'name.efi\xFF')

@gbuloz commented on GitHub (May 27, 2025): Same issue with kea 2.6.2 on Fedora 41 when booting a 10 years old Kontron VX3040 Intel CPU board. After some debug with tcpdump I noticed an extra FF at the end of the filename requested to the TFTP server. As a workaround I've renamed the boot files on the server with an extra FF at the end of their names using : mv name.efi $(echo -en 'name.efi\xFF')

kerem commented

2026-03-01 18:37:02 +03:00

Author

Owner

@BloodBlight commented on GitHub (May 27, 2025):

Oh, that's a great little hack! I can even script out that creation. Thank you for sharing!

@BloodBlight commented on GitHub (May 27, 2025): Oh, that's a great little hack! I can even script out that creation. Thank you for sharing!

kerem commented

2026-03-01 18:37:02 +03:00

Author

Owner

@Koli0842 commented on GitHub (Jun 3, 2025):

I have also encountered this (Ubiquiti USG, and an old Z77X-UD3H with an Atheros NIC), the above hack worked. Instead of moving, I created symlinks for all bootable entities, it still works

@Koli0842 commented on GitHub (Jun 3, 2025): I have also encountered this (Ubiquiti USG, and an old Z77X-UD3H with an Atheros NIC), the above hack worked. Instead of moving, I created symlinks for all bootable entities, it still works

kerem commented

2026-03-01 18:37:02 +03:00

Author

Owner

@BloodBlight commented on GitHub (Jun 3, 2025):

As this is NOT a bug with netbootxyz, but rather an issue with with DHCP, I am open to closing this ticket. Maybe taking the notes from it and this "hack" and putting it into the docs?

@BloodBlight commented on GitHub (Jun 3, 2025): As this is NOT a bug with netbootxyz, but rather an issue with with DHCP, I am open to closing this ticket. Maybe taking the notes from it and this "hack" and putting it into the docs?

kerem commented

2026-03-01 18:37:02 +03:00

Author

Owner

@Koli0842 commented on GitHub (Jun 3, 2025):

Sounds good to me, took some digging to find this.

@Koli0842 commented on GitHub (Jun 3, 2025): Sounds good to me, took some digging to find this.

kerem commented

2026-03-01 18:37:02 +03:00

Author

Owner

@bwann commented on GitHub (Aug 9, 2025):

I did a bunch of digging into this problem and reading of UEFI specs a while back and I'm pretty sure what is happening is UEFI bugs around line terminations, at least when using UEFI PXE on IPv4. This comes down to using the fixed length "file" field in the DHCP header vs using Option 67 for providing a boot filename, and how different UEFI implementations handle line and field terminations in DHCPv4 packets.

RFC 2132 does not guarantee the filename in option 67 is null terminated. In the UEFI 2.6 spec DHCP options are treated as variable length fields in the form of "option code + length of option data + option data" but the spec does not address line terminations at all, that's left as an implementation detail. So some handle the filename in option 67 correctly and some don't.

For example for several of my SuperMicro boards given only option 67 (no higher numbered options) as "testfilename", the packet will contain 0x48 (decimal 67), 0x0C (length 12), the filename, and then 0xff at the end of the packet. They should read 12 bytes and stop, but what they do is keep reading data in as the filename right to the end of the packet as if they're expecting a null terminated string and not a variable-length-field. That's what gets the junk added to the end of TFTP filenames. I demonstrated this by adding some data to option 68 so it follows next in the same packet and their UEFI PXE code kept reading in the data in option 68 as part of the TFTP filename!

The way I see to fix this is not to use option 67 when providing a boot filename, but the actual 'file' field in the DHCP header. At least in Kea this is done as providing "boot-file-name" in the top level Dhcp4 (or class) config, and not in "option-data". Or pray and complain to the vendor they fix their UEFI.

Interestingly DHCPv6 doesn't have this problem because it's all variable-length-fields. The Tianocore EDK II reference UEFI implementation also goes out of its way to call out the ambiguous line termination with Option 67 and tries to do the right thing. I have a writeup a did that contains code snippets and examples: https://binaryfury.wann.net/2024/12/pxe-two-tftp-filenames-one-dhcp-offer-plus-weird-filenames/

@bwann commented on GitHub (Aug 9, 2025): I did a bunch of digging into this problem and reading of UEFI specs a while back and I'm pretty sure what is happening is UEFI bugs around line terminations, at least when using UEFI PXE on IPv4. This comes down to using the fixed length "file" field in the DHCP header vs using Option 67 for providing a boot filename, and how different UEFI implementations handle line and field terminations in DHCPv4 packets. RFC 2132 does not guarantee the filename in option 67 is null terminated. In the UEFI 2.6 spec DHCP options are treated as variable length fields in the form of "option code + length of option data + option data" but the spec does not address line terminations at all, that's left as an implementation detail. So some handle the filename in option 67 correctly and some don't. For example for several of my SuperMicro boards given only option 67 (no higher numbered options) as "testfilename", the packet will contain 0x48 (decimal 67), 0x0C (length 12), the filename, and then 0xff at the end of the packet. They should read 12 bytes and stop, but what they do is keep reading data in as the filename right to the end of the packet as if they're expecting a null terminated string and not a variable-length-field. That's what gets the junk added to the end of TFTP filenames. I demonstrated this by adding some data to option 68 so it follows next in the same packet and their UEFI PXE code kept reading in the data in option 68 as part of the TFTP filename! The way I see to fix this is not to use option 67 when providing a boot filename, but the actual 'file' field in the DHCP header. At least in Kea this is done as providing "boot-file-name" in the top level Dhcp4 (or class) config, and not in "option-data". Or pray and complain to the vendor they fix their UEFI. Interestingly DHCPv6 doesn't have this problem because it's all variable-length-fields. The Tianocore EDK II reference UEFI implementation also goes out of its way to call out the ambiguous line termination with Option 67 and tries to do the right thing. I have a writeup a did that contains code snippets and examples: https://binaryfury.wann.net/2024/12/pxe-two-tftp-filenames-one-dhcp-offer-plus-weird-filenames/

kerem commented

2026-03-01 18:37:02 +03:00

Author

Owner

@antonym commented on GitHub (Aug 9, 2025):

@claude can you summarize this for a kb article for https://github.com/netbootxyz/netboot.xyz-docs

@antonym commented on GitHub (Aug 9, 2025): @claude can you summarize this for a kb article for https://github.com/netbootxyz/netboot.xyz-docs

kerem commented

2026-03-01 18:37:02 +03:00

Author

Owner

@claude[bot] commented on GitHub (Aug 9, 2025):

Claude finished @antonym's task —— View job

Creating Knowledge Base Article Summary

I've analyzed the issue thread and created a comprehensive KB article summary about TFTP filename interpretation problems.

Todo List:

Analyze the issue thread and extract key technical details
Identify root causes and affected hardware/software combinations
Document all known workarounds and solutions
Create formatted KB article summary suitable for documentation

KB Article: TFTP Filename Interpretation Issues with Older PXE Clients

Problem Description

Older PXE clients (typically 10+ years old) may append extra characters to TFTP filenames, causing "File not found" errors. The issue manifests as Unicode replacement characters (�) or hex bytes (often 0xFF) being added to the end of requested filenames.

Root Cause

This is a UEFI PXE implementation bug related to DHCP filename handling:

Technical Issue: UEFI PXE clients incorrectly handle DHCP Option 67 (boot filename)
Expected Behavior: Option 67 should be treated as a variable-length field
Actual Behavior: Some implementations treat it as a null-terminated string, reading beyond the specified length
Result: Extra bytes from the DHCP packet get appended to the TFTP filename request

Affected Hardware/Software

Hardware:

Jetway J7F4K1G5DS-LF and similar older boards
Lenovo T460 laptops
Z77X-UD3H motherboards with Atheros NICs
Kontron VX3040 Intel CPU boards
Generally affects Intel UNDI PXE-2.1 implementations from ~2000 era

DHCP Servers:

Kea DHCP (problematic)
UniFi USG devices (limited configuration options)
pfSense with Kea DHCP

Working Combinations:

pfSense with deprecated isc-dhcp
Properly configured OpnSense/isc-dhcp setups

Workarounds and Solutions

1. Server-Side File Naming (Recommended)

Create boot files with the extra 0xFF byte in the filename:

# Rename files to include the extra byte
mv netboot.xyz.kpxe $(echo -en 'netboot.xyz.kpxe\xFF')
mv netboot.xyz.efi $(echo -en 'netboot.xyz.efi\xFF')

# Or create symlinks (cleaner approach)
ln -s netboot.xyz.kpxe $(echo -en 'netboot.xyz.kpxe\xFF')
ln -s netboot.xyz.efi $(echo -en 'netboot.xyz.efi\xFF')

2. DHCP Configuration Changes

For isc-dhcp servers, use the boot-file-name directive instead of Option 67:

# In dhcp4 config, use boot-file-name at the top level
boot-file-name "netboot.xyz.kpxe";

# Instead of in option-data

For pfSense users: Switch from Kea to the deprecated isc-dhcp service in System > Advanced > Networking.

3. Remove DHCP boot-filename Option

Some users report success by removing the option bootfile-name directive entirely, though this may break other clients.

Technical Details

The issue specifically affects DHCPv4 Option 67 handling
DHCPv6 does not have this problem due to its variable-length field design
RFC 2132 does not guarantee null termination of Option 67 filenames
UEFI 2.6 spec leaves line termination as an implementation detail

Troubleshooting Steps

Identify the issue: Look for replacement characters (�) or extra bytes in TFTP server logs
Packet capture: Use tcpdump to verify extra bytes in TFTP requests
Test workarounds: Try the server-side filename solution first
DHCP server evaluation: Consider switching from Kea to isc-dhcp if possible

Prevention

Use the boot-file-name directive in DHCP configuration instead of Option 67
Test with known problematic hardware before deployment
Document affected clients in your environment

References

Issue discussion: https://github.com/netbootxyz/netboot.xyz/issues/1198
Technical analysis: https://binaryfury.wann.net/2024/12/pxe-two-tftp-filenames-one-dhcp-offer-plus-weird-filenames/
UEFI Specification 2.6+
RFC 2132 (DHCP Options)

@claude[bot] commented on GitHub (Aug 9, 2025): **Claude finished @antonym's task** —— [View job](https://github.com/netbootxyz/netboot.xyz/actions/runs/16853395658) --- ### Creating Knowledge Base Article Summary I've analyzed the issue thread and created a comprehensive KB article summary about TFTP filename interpretation problems. **Todo List:** - [x] Analyze the issue thread and extract key technical details - [x] Identify root causes and affected hardware/software combinations - [x] Document all known workarounds and solutions - [x] Create formatted KB article summary suitable for documentation --- ## KB Article: TFTP Filename Interpretation Issues with Older PXE Clients ### Problem Description Older PXE clients (typically 10+ years old) may append extra characters to TFTP filenames, causing "File not found" errors. The issue manifests as Unicode replacement characters (�) or hex bytes (often 0xFF) being added to the end of requested filenames. ### Root Cause This is a UEFI PXE implementation bug related to DHCP filename handling: - **Technical Issue**: UEFI PXE clients incorrectly handle DHCP Option 67 (boot filename) - **Expected Behavior**: Option 67 should be treated as a variable-length field - **Actual Behavior**: Some implementations treat it as a null-terminated string, reading beyond the specified length - **Result**: Extra bytes from the DHCP packet get appended to the TFTP filename request ### Affected Hardware/Software **Hardware:** - Jetway J7F4K1G5DS-LF and similar older boards - Lenovo T460 laptops - Z77X-UD3H motherboards with Atheros NICs - Kontron VX3040 Intel CPU boards - Generally affects Intel UNDI PXE-2.1 implementations from ~2000 era **DHCP Servers:** - Kea DHCP (problematic) - UniFi USG devices (limited configuration options) - pfSense with Kea DHCP **Working Combinations:** - pfSense with deprecated isc-dhcp - Properly configured OpnSense/isc-dhcp setups ### Workarounds and Solutions #### 1. Server-Side File Naming (Recommended) Create boot files with the extra 0xFF byte in the filename: ```bash # Rename files to include the extra byte mv netboot.xyz.kpxe $(echo -en 'netboot.xyz.kpxe\xFF') mv netboot.xyz.efi $(echo -en 'netboot.xyz.efi\xFF') # Or create symlinks (cleaner approach) ln -s netboot.xyz.kpxe $(echo -en 'netboot.xyz.kpxe\xFF') ln -s netboot.xyz.efi $(echo -en 'netboot.xyz.efi\xFF') ``` #### 2. DHCP Configuration Changes **For isc-dhcp servers**, use the `boot-file-name` directive instead of Option 67: ``` # In dhcp4 config, use boot-file-name at the top level boot-file-name "netboot.xyz.kpxe"; # Instead of in option-data ``` **For pfSense users**: Switch from Kea to the deprecated isc-dhcp service in System > Advanced > Networking. #### 3. Remove DHCP boot-filename Option Some users report success by removing the `option bootfile-name` directive entirely, though this may break other clients. ### Technical Details - The issue specifically affects DHCPv4 Option 67 handling - DHCPv6 does not have this problem due to its variable-length field design - RFC 2132 does not guarantee null termination of Option 67 filenames - UEFI 2.6 spec leaves line termination as an implementation detail ### Troubleshooting Steps 1. **Identify the issue**: Look for replacement characters (�) or extra bytes in TFTP server logs 2. **Packet capture**: Use tcpdump to verify extra bytes in TFTP requests 3. **Test workarounds**: Try the server-side filename solution first 4. **DHCP server evaluation**: Consider switching from Kea to isc-dhcp if possible ### Prevention - Use the `boot-file-name` directive in DHCP configuration instead of Option 67 - Test with known problematic hardware before deployment - Document affected clients in your environment ### References - Issue discussion: https://github.com/netbootxyz/netboot.xyz/issues/1198 - Technical analysis: https://binaryfury.wann.net/2024/12/pxe-two-tftp-filenames-one-dhcp-offer-plus-weird-filenames/ - UEFI Specification 2.6+ - RFC 2132 (DHCP Options) ---

Rows
Columns

[GH-ISSUE #1198] Filename not properly interpreted by TFTP #1870

Creating Knowledge Base Article Summary

KB Article: TFTP Filename Interpretation Issues with Older PXE Clients

Problem Description

Root Cause

Affected Hardware/Software

Workarounds and Solutions

1. Server-Side File Naming (Recommended)

2. DHCP Configuration Changes

3. Remove DHCP boot-filename Option

Technical Details

Troubleshooting Steps

Prevention

References