# This README and grub configuration files are released under the
# the terms of the GPL (GNU GENERAL PUBLIC LICENSE) version 2
# See COPYING file for more details.

# Author: Thomas Renninger <trenn@suse.de>
# Copyright (C) 2019 Thomas Renninger <trenn@suse.de>

This directory contains grub boot loader (version 2.02)
configuration files.
The directory structure is exactly synced (e.g. via cobbler sync)
to the tftp (or http/www for http network boot) directory and must
be kept as is.



IMPORTANT FILES
===============

config/grub
-----------

grub.cfg
-> This file is loaded when Client Architecture Support
   negotiation in the kernel stub on ppc64(le) requires
   a reboot and grub is reloaded.
   It is not clear if the firmware interface has a problem
   or grub or Linux call it incorrectly.
   Normally grub should already set the prefix to the
   directory where it has been loaded from (grub
   subdirectory in our case).
   We simply set prefix="grub" and manually load the
   main config file grub/grub.cfg


grub/grub.cfg
-> This is the main entry point for all architectures.
   We always load this config file.

grub/grub/local_*.cfg
-> This are the architecture specific config files providing
   local (hard disk) boot entries.
   These may need adjusting over the time, depending how
   distributions name their *.efi executable for local boot

grub/grub/system/*
-> Empty directory where cobbler will sync machine specific
   configuration (typically setting local boot or an (auto-)install
   menu entry).
   These are named after the mac address of a machine, e.g.:
   grub/system/52:54:00:42:07:04
   This config file is tried to be loaded from the main grub.cfg

grub/grub/system_link.*
-> Empty directory where cobbler will create symlinks, named after
   the cobbler name of the machine and it links to above described
   mac address file in ../system/${mac}
   This is only for easier reading and debugging of machine specific
   grub settings.


/var/lib/cobbler/loaders
------------------------

This directory holds network bootloaders (or links to them) and is also
synced to /srv/tftp root directory 1 to 1.
Its contents is created in the post (removed in postun) section of the
cobbler.spec file.
This is done via scripts/mkgrub.sh shell script.
It creates grub executables for each installed grub2-$arch via:
grub2-mkimage and links in the corresponding grub2 modules and other
supported bootloaders (pxelinux.0,...)

If you have installed e.g. a new grub or syslinux version, you should
re-run mkgrub.sh to build new grub executables.
For other, static or already compiled/linked bootloaders like, shim,
pxelinux.0 or a precompiled, signed grub.efi executable, it is enough
to call "cobbler sync" now (we store links to these now).

The grub specific files generated/linked via mkgrub.sh are also described
here:

.cobbler_postun_cleanup
-> Filled up with generated grub2-mkimage binaries and created links
   This is need in postun cobbler.spec section to remove things again.
   This is the only, not synced file.

grub/grub.0
-> 32 bit PXE (x86 legacy) grub executable.
  grub2-mkimage generated.
  This can/should be used instead of pxelinux.0. You then get the full
  grub boot process.
  The bootloader is named grub.0, because pxelinux.0 can chain boot
  this grub exectuble via network. But it (or specific versions?) wants
  boot loaders with a filename ending on .0

grub/{grubaa64.efi,grub.ppc64le,grubx64.efi}
-> Also grub2-mkimage generated, architecture specific grub executables
   These, can directly be network booted on the corresponding/matching
   architecture. Please have a look at the dhcpd.conf template for
   getting an idea how architecture differing (via dhcp request network
   packets) works.
   On grub-${arch} package updates, please call scripts/mkgrub.sh to get
   up-to-date exectubles.
   The names of these executables are derived from grub2 sources.
   These are the default names as they should get generated on all
   distributions by default. These map to ${grub-cpu}-${grub-platform} as seen
   below the modules directory structure. Unfortunately this does not map 1 to
   1.

grub/{arm64-efi,i386-pc,powerpc-ieee1275,x86_64-efi}
-> links to architecture specific grub modules. From these grub2-mkimage
   generates above executables.

   These directories (where the links point to) have to be named exactly like
   this. grub may download missing/needed modules from
   /srv/tftp/${prefix}/${grub-cpu}-${grub-platform} on the fly as needed.
   E.g. using the grub.cfg command: hello, will end up in downloading
   hello.mod
   then doing automatically an "insmod hello"...

grub/{grub.efi,shim.efi}
-> links to precompiled from distribution provided and signed shim and grub
   efi executables.
   By default shim.efi is used in UEFI (x86 at least) case.
   shim.efi automatically tries to load grub.efi.
   Module loading via network using a signed grub.efi loader, does not work.
   All grub modules needed grub.cfg and later sourced config files must be
   present in the signed grub.efi executable.
   For example the "tr" grub module was not part of SLES 12 and therefore the
   reforming of the ${mac} address to the previous pxelinux.0 style, e.g.:
   52:54:00:42:56:58 -> 01-52-54-00-42-56-58
   does not work. But this is overhead anyway, so we now use the plain MAC
   address as filenames for system specific grub configuration.

