[PATCH v6 5/5] docs: Update info with grub.cfg netboot selection order

[Javier Martinez Canillas]

From: Robert Marshall <address@hidden>

Add documentation to the GRUB manual that specifies the order netboot
clients use to select a GRUB configuration file.

Also explain that the feature is enabled by default but can be disabled
by setting the 'feature_net_search_cfg' environment variable to 'n' in
an embedded configuration file.

Signed-off-by: Robert Marshall <address@hidden>
Signed-off-by: Javier Martinez Canillas <address@hidden>

---

Changes in v6:
- Explain in the GRUB manual that the feature is enabled by default and how
  can be disabled by setting a variable in an embedded configuration file.

Changes in v5:
- Add Reviewed-by tag from Daniel Kiper to patch #5.

Changes in v4:
- Mention that the UUID is unique to the machine and not the NIC and also
  refer to the RFC 4578 where the client UUID DHCP option is specified.

Changes in v3:
- Add a patch documenting the grub.cfg netboot selection order.

Changes in v2: None

 docs/grub.texi | 51 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/docs/grub.texi b/docs/grub.texi
index 1b25466c735..83979af381d 100644
--- a/docs/grub.texi
+++ b/docs/grub.texi
@@ -2495,6 +2495,57 @@ grub-mknetdir --net-directory=/srv/tftp 
--subdir=/boot/grub -d /usr/lib/grub/i38
 Then follow instructions printed out by grub-mknetdir on configuring your DHCP
 server.
 
+The grub.cfg file is placed in the same directory as the path output by
+grub-mknetdir hereafter referred to as FWPATH. GRUB will search for its
+configuration files in order using the following rules where the appended
+value corresponds to a value on the client machine.
+
+@example
+@group
+@samp{(FWPATH)}/grub.cfg-@samp{(UUID OF MACHINE)}
+@samp{(FWPATH)}/grub.cfg-@samp{(MAC ADDRESS OF NIC)}
+@samp{(FWPATH)}/grub.cfg-@samp{(IPv4 OR IPv6 ADDRESS)}
+@samp{(FWPATH)}/grub.cfg
+@end group
+@end example
+
+The UUID is the Client Machine Identifier Option Definition as specified in
+RFC 4578. The client will only attempt to loouk up a UUID config file if it
+was provided by the DHCP server.
+
+The client will only attempt to look up an IPv6 address config once, however,
+it will try the IPv4 multiple times. The concrete example below shows what
+would happen under the IPv4 case.
+
+@example
+@group
+UUID: 7726a678-7fc0-4853-a4f6-c85ac36a120a
+MAC:  52:54:00:ec:33:81
+IPV4: 10.0.0.130 (0A000082)
+@end group
+@end example
+
+@example
+@group
+@samp{(FWPATH)}/grub.cfg-7726a678-7fc0-4853-a4f6-c85ac36a120a
+@samp{(FWPATH)}/grub.cfg-52-54-00-ec-33-81
+@samp{(FWPATH)}/grub.cfg-0A000082
+@samp{(FWPATH)}/grub.cfg-0A00008
+@samp{(FWPATH)}/grub.cfg-0A0000
+@samp{(FWPATH)}/grub.cfg-0A000
+@samp{(FWPATH)}/grub.cfg-0A00
+@samp{(FWPATH)}/grub.cfg-0A0
+@samp{(FWPATH)}/grub.cfg-0A
+@samp{(FWPATH)}/grub.cfg-0
+@samp{(FWPATH)}/grub.cfg
+@end group
+@end example
+
+This feature is enabled by default but it can be disabled by setting the
+@samp{feature_net_search_cfg} to @samp{n}. Since this happens before the
+configuration file is read by GRUB, this option has to be disabled in an
+embedded configuration file (@pxref{Embedded configuration}).
+
 After GRUB has started, files on the TFTP server will be accessible via the
 @samp{(tftp)} device.
 
-- 
2.24.1