github.com/mvdan/u-root-coreutils@v0.0.0-20230122170626-c2eef2898555/pkg/boot/systembooter/README.md (about)

     1  # Booter package
     2  
     3  The booter package provides a Booter interface that allows to define custom ways
     4  of booting a machine. Booter only requires a method to get its name, and a
     5  method to boot the machine. This interface is suitable to be used by
     6  Systemboot's `uinit`.
     7  
     8  Each custom booter will define their own name (e.g. "netboot") and the custom
     9  logic to boot. For example, a network booter may try to get a network
    10  configuration via DHCPv6, download a boot program, and run it.
    11  
    12  The custom booter also needs to provide a way to be initialized. This is usually
    13  done by defining a function called "New<MyBooterName>" (e.g. "NewNetBooter").
    14  This function takes as input a sequence of bytes, representing the booter
    15  configuration, and will return a Booter object, or an error.
    16  
    17  The exact format of the boot configuration is determined by the custom booter,
    18  but there is a general structure that every booter configuration has to provide.
    19  This is discussed in the Booter configuration section below
    20  
    21  ## Booter configuration
    22  
    23  A Booter configuration is a JSON file with a simple structure. The requirements
    24  are:
    25  
    26  * the top level object is a map
    27  * the map contains at least a "type" field, with a string value that holds the
    28    booter's name
    29  * the JSON should not be nested. This is recommended for simplicity but is not
    30    strictly required
    31  
    32  For example, the NetBooter configuration can be like the following:
    33  
    34  ```
    35  {
    36      "type": "netboot",
    37      "method": "<method>",
    38      "mac": "<mac address",
    39      "override_url": "<url>"
    40  }
    41  ```
    42  
    43  where:
    44  
    45  * "type" is required, and its value is always "netboot" (otherwise it's not
    46    recognized as a NetBooter)
    47  * "method" is required, and can be either "dhcpv6", "dhcpv4" or "slaac"
    48  * "mac" is required, and it is the MAC address of the interface that will try
    49    to boot from the network. It has the "aa:bb:cc:dd:ee:ff" format
    50  * "override_url" is optional, unles "method" is "slaac", and it is the URL from
    51    which the booter will try to download the network boot program
    52  
    53  
    54  ## Creating a new Booter
    55  
    56  To create a new Booter, the following things are necessary:
    57  
    58  * define a structure for the new booter, that implements the Booter interface
    59    described above. I.e. implement the `TypeName` and `Boot` methods
    60  * define a NewMyBooterName (e.g. "NewLocalBoot") that takes a sequence of bytes
    61    as input, and return a `Booter` or an error if it's an invalid or unknown
    62    configuration. The input byte sequence must contain a valid JSON configuration
    63    for that booter in order to return successfully
    64  * the new booter has to be registered as a supported booter. Just add the
    65    `NewMyBooterName` function (however this function is called) to the
    66    `supportedBooterParsers` in `bootentry.go`. This array is used by
    67    `GetBootEntries` to test a boot configuration against all the available
    68    booters
    69