mirror of
https://github.com/netbootxyz/netboot.xyz-docs.git
synced 2026-04-25 15:05:53 +03:00
[GH-ISSUE #149] Create kb article tftp file name issues #196
Labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
starred/netboot.xyz-docs#196
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Originally created by @antonym on GitHub (Aug 9, 2025).
Original GitHub issue: https://github.com/netbootxyz/netboot.xyz-docs/issues/149
See https://github.com/netbootxyz/netboot.xyz/issues/1198
@antonym commented on GitHub (Aug 9, 2025):
@claude make a PR for a knowledge base article based on the link referenced in the issue
@claude[bot] commented on GitHub (Aug 9, 2025):
Claude finished @antonym's task —— View job •
claude/issue-149-20250809-2118• Create PR ➔Creating Knowledge Base Article for TFTP File Name Issues ✅
Successfully created a comprehensive knowledge base article for TFTP filename issues and troubleshooting.
Task List:
Summary
Created a new knowledge base article at
docs/kb/networking/tftp-filename-issues.mdthat covers:The article provides practical solutions for users experiencing TFTP boot issues with netboot.xyz and includes configuration examples for various DHCP servers.
@antonym commented on GitHub (Aug 10, 2025):
@claude using this information prepare a kb article with the proper formatting:
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
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.
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 10, 2025):
Claude finished @antonym's task —— View job •
claude/issue-149-20250810-1439• Create PR ➔Creating KB Article for TFTP Filename Issues ✅
Successfully created a comprehensive knowledge base article for TFTP filename interpretation issues with older PXE clients.
Task List:
Summary
Created a new knowledge base article at
docs/kb/networking/tftp-filename-issues.mdthat covers:The article follows the repository's documentation structure and includes proper frontmatter, code examples, and references to the original issue discussion and technical analysis.