h1. 3 State Boot Support

{{toc}}

Foreman 1.1 now supports a 3 state boot model. This document describes the behaviour of the system, and how to make use of it.

h2. The old way

Until now Foreman has only ever cared about 2 states. A machine is either:

* Known to Foreman _and_ in Build mode

  - A MAC-specific PXE file is written to launch the installer

* Known to Foreman _and not_ in Build mode, _or_ unknown to Foreman

  - The global default PXE file instructs the machine to localboot

This makes it impossible to handle unknown machines separately from known, built machines.

h2. The new way

We now separate the last two states:

* Known to Foreman _and_ in Build mode

  - A MAC-specific PXE file is written to launch the installer

* Known to Foreman _and not_ in Build mode

  - A MAC-specific PXE file is written to instruct localboot

* Unknown to Foreman

  - The global default PXE file instructs the machine to _whatever_

h2. How it works

Until now, we've relied on a single, global default template (PXE Default File) which is written to all the proxies via the button on the Provisioning Template page.

We now add a new global template (PXE Localboot Default). This does not need to be deployed to all the proxies, as it will be written when a host exits Build mode. So our state+file list becomes:

* Known to Foreman _and_ in Build mode

  - A MAC-specific PXE file is written (OS-specific installer template)

* Known to Foreman _and not_ in Build mode

  - A MAC-specific PXE file is written (Global PXE Localboot template)

* Unknown to Foreman

  - The global default PXE file is used (PXE Default File template)

h2. Defaults to 'off'

Actually, this feature is always on. However, by default, the two global templates contain the same PXE instructions (i.e. boot from local disk). Thus, the current behaviour of Foreman is preserved - if a machine is unknown _or_ not in build mode, it will get a template that instructs it to boot from local disk.

h2. How to use it

Suppose you want all unknown hardware to boot into a custom ramdisk image that you have added to the TFTP server. To do this simply, edit the PXE Default File template to represent your desired behaviour. For example:

    DEFAULT menu

PROMPT 0

MENU TITLE PXE Menu

TIMEOUT 200

TOTALTIMEOUT 6000

ONTIMEOUT isoboot

LABEL isoboot

   LINUX boot/memdisk

   INITRD boot/foreman.iso

   APPEND iso raw

Then click Build PXE Default to redeploy the Global template.

h2. Caveats

Currently the system will deploy the global template to _all_ TFTP proxies. That may cause unintended behaviour if you want to boot-to-ramdisk only on a single network.

One workaround would be to manually fix the default file for the appropriate subnet after deploying the template.