ISO Compatibility¶

This document describes how to add Windows ISO injection compatibility your Playbook, allowing users of your Playbook to create custom ISOs that run your playbook after first boot.

Prerequisite Knowledge¶

There are two steps to making and using custom ISOs. The first step happens on the machine that creates the ISO, which we call the injection step. The second step occurs after the user has installed Windows from the injected ISO, which we call the OOBE step.

Injection¶

During ISO injection, AME Beta makes the following changes to the ISO:

Removes uncommon Windows editions
Removes Windows Defender if the playbook specifies the DefenderDisabled requirement
Runs any playbook YAML actions that specify iso: true/only, which includes !download actions by default. Note that !software actions automatically download and cache chocolatey packages during this step.

For safety reasons, only certain actions are allowed during ISO injection. Dynamic actions like running scripts or commands are NOT supported, and must be run during the OOBE step.
Injects the custom AME OOBE (Out-of-Box Experience UI) process, along with your playbook files for use during the OOBE

OOBE¶

OOBE stands for Out-of-Box Experience, which is simply a fancy term for the graphical UI that the user is greeted with after installing Windows. This UI handles license agreements, as well as any prerequisites like internet connection, Windows activation, or similar.

In future, the user will also be able to configure credentials, software, and playbook features here as well.

After the user has completed any prerequisites and configuration changes, your playbook will then be run.

Note

When your playbook is run during this step, any !software actions will automatically install from its cached package, thus not requiring internet. Similarly !download actions will simply be skipped since it was already run during injection. Note that you can set oobe: true to make it also attempt a newer download during the OOBE.

Recommendations¶

Before allowing users to inject an ISO with your playbook, we recommend making any actions that require internet, such as software downloads, occur before first boot and instead during ISO injection. You can do this by using the built-in !software and/or !download actions which automatically run during injection, caching the downloads.

Adding ISO Compatibility¶

With that over with, we can begin making your playbook ISO compatible.

Playbook Configuration¶

Start by making the following changes to your playbook.conf file:

Add an OOBE element with 3 BulletPoint elements of choice inside, like so:

<OOBE>
  <BulletPoints>
    <BulletPoint Icon="Lock" Title="Reliable"
    Description="Through thorough testing, we've done our best to ensure that this is a reliable deployment process."/>
    <BulletPoint Icon="Privacy" Title="Enhanced privacy"
    Description="The process will enhance your privacy using various methods, such as removing privacy infringing services."/>
    <BulletPoint Icon="Rocket" Title="Optimized"
    Description="New default apps, performance optimizations, and refined UI changes will all be implemented."/>
  </BulletPoints>
</OOBE>

Important

The Description and Title lengths must roughly match the lengths in the examples above.

These will be displayed on a summary page in the OOBE.

Currently, only the Lock, Privacy, and Rocket icons are available for use.

Note

Optionally, you can specify an internet requirement level too like so:

<OOBE>
  <!-- ... -->

  <!-- Request the user for internet, and show
       a warning if they do not connect -->
  <Internet>Request</Internet>
  <!-- Force the user to connect to the internet -->
  <Internet>Force</Internet>
</OOBE>

Optionally, add an ISO element to disable BitLocker and/or hardware requirements in the ISO:

<ISO>
  <DisableBitLocker>true</DisableBitLocker>
  <DisableHardwareRequirements>true</DisableHardwareRequirements>
</ISO>

Enable ISO support by adding the SupportsISO element like so:
```
<SupportsISO>true</SupportsISO>
```

In the end, you should have something like this:

<Playbook>
  <!-- ... -->
  <SupportsISO>true</SupportsISO>
  <OOBE>
    <BulletPoints>
      <BulletPoint Icon="Lock" Title="Reliable"
      Description="Through thorough testing, we've done our best to ensure that this is a reliable deployment process."/>
      <BulletPoint Icon="Privacy" Title="Enhanced privacy"
      Description="The process will enhance your privacy using various methods, such as removing privacy infringing services."/>
      <BulletPoint Icon="Rocket" Title="Optimized"
      Description="New default apps, performance optimizations, and refined UI changes will all be implemented."/>
    </BulletPoints>
  </OOBE>
  <ISO>
    <DisableBitLocker>true</DisableBitLocker>
    <DisableHardwareRequirements>true</DisableHardwareRequirements>
  </ISO>
  <!-- ... -->
</Playbook>

Optionally add a Software list so users can see which software will be installed in the OOBE:
```
<Software>
  <Package Option="browser-firefox">
    <Name>firefox</Name>
    <Title>Firefox</Title>
    <Description>Fully featured web browser, configured for optimal usability and privacy.</Description>
    <Icon>firefox.png</Icon>
  </Package>
</Software>
```
In this example, the AME OOBE will visually list Firefox as a software package to be installed, assuming the browser-firefox option was chosen during ISO creation.

Icon must point to a file inside an Images folder in the root of your playbook.

Name should ideally correspond to the package property on a !software or !download action, which will in future allow for the user to toggle installing that software during the OOBE.

YAML Customization¶

Your playbook should now be ISO compatible, however there are a few more things you should know.

By default, all actions (except !download) run during the OOBE on the live system. However, in some cases, you may want to run an action during injection on the offline ISO. In fact, this may be preferable for actions that remove services or certain system software, since offline modifications can be more reliable.

To control how actions behave during ISO injection and the OOBE, we provide two properties that are available on all actions:

oobe: Specifies whether or not an action is run during the OOBE after installing from a custom ISO.

The available options are as follows:
null: Run during OOBE unless iso: true/only is specified
true: Always run during OOBE
false: Never run during OOBE
only: Only run during OOBE, and not during typical playbook runs.
iso: Specifies whether or not an action is run during ISO injection.

The available options are as follows:
true: Always run during ISO injection
false: Never run during ISO injection
only: Only run during ISO injection, and not during typical playbook runs.

Example:
- !service: name: "wuauserv" operation: delete iso: true
In this case, the wuauserv (Windows Update) service will be deleted in the ISO itself during injection, and this action will be skipped during the OOBE. If you also wanted this to run during the OOBE for redundancy, you could explicitly specify oobe: true in addition to iso: true.

Regarding the Software packages mentioned above in playbook.conf, you can link a !software or !download action to a given package using the package property like so:

- !software:
  name: "Firefox"
  source: chocolatey
  option: "browser-firefox"
  package: 'firefox'
  weight: 150

This is all you need to know to create a fully ISO compatible playbook. If you have any questions or feedback, please contact @styris_ame on Discord or Telegram.