> For the complete documentation index, see [llms.txt](https://documentation.2pintsoftware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.2pintsoftware.com/2pxe-server/4.0/configuration/2pxe-config-file/powershell-request-handler.md).

# PowerShell Request Handler

The PowerShell request handler lets your own PowerShell scripts decide whether a device boots and which Windows PE boot images it is offered. This allows 2PXE to run standalone, without Configuration Manager or Windows Deployment Services, and to query or update other data sources during the boot. (Do not confuse these scripts with the iPXE Anywhere Web Service PowerShell scripts.)

## Requirements

* **Integration mode** set to **PowerShell**.
* The two scripts, specified by **Allow boot script** and **Boot images** (PowerShell settings). Sample scripts are installed in the 2PXE installation folder: `PowerShellExtensionAllowBoot.ps1` and `PowerShellExtensionBootImages.ps1`. If a script does not exist, 2PXE does not boot the device.
* Boot images stored in the `Sources` folder under the RemoteInstall folder (by default `%ProgramData%\2Pint Software\2PXE\Remoteinstall\Sources`), one folder per boot image, each containing a `.wim` file. If a script returns a folder that does not exist or has no `.wim` file, 2PXE does not boot the device.

## How it works

1. **Allow boot script.** When a device sends its first PXE request, 2PXE runs the allow boot script. The script receives a `$SessionData` parameter with the request, including `$SessionData.ComputerIdentifier.MacAddress`, `.SMBios_Guid` and `.architecture`. It must return a `Zipper.Zpxe.RequestHandlers.Powershell.BootObject` with `PSShouldBoot` set to `$true` to boot the device, or `$false` to ignore it. This script can run several times for each boot, depending on the device's PXE firmware.
2. **Boot images script.** Once the boot loader is running, 2PXE runs the boot images script. When using iPXE boot loaders, `$SessionData` contains the values reported by iPXE, such as `mac`, `uuid`, `arch`, `platform`, `make`, `model` and `serial` (for example, `$SessionData["arch"]`). The script returns a `BootObject` with:

   * `PSBootImage`: a hash table of boot images to offer, where each key is the name of a folder under `Sources` and each value is its architecture (`x86`, `x64` or `arm64`). For example, `$bootimages.Add("WinPE-x64","x64")`.
   * `PSShouldBoot`: `$false` to stop the boot.
   * `PSBootForce`: `$true` to skip the "press a key to boot" prompt.
   * `PSbootURL` (optional): a different web server URL to download wimboot and the boot images from, instead of the 2PXE server.

   If the sample script does not add any boot images, it falls back to offering every folder under `Sources`, reading each `.wim` file's architecture.
3. Unless `PSBootForce` is set, the user must press the boot key (**AcceptBootKeyEFI**/**AcceptBootKeyBIOS**) within **iPXEF12PromptTimeout**, otherwise the device exits to its next boot device.
4. 2PXE shows a menu listing **Boot to** *architecture name* for each returned boot image, followed by **Reboot Computer** and **Exit to next boot device**. The selected boot image is downloaded from the 2PXE web service (or `PSbootURL`) and started with wimboot. Without iPXE boot loaders, 2PXE creates a BCD file for the boot images instead, and the Windows boot loaders download them with TFTP.

## Custom task sequence variables

2PXE can also supply custom task sequence variables, using the add variables script (by default `PowerShellExtensionAddVariables.ps1` in the 2PXE installation folder). The script receives the same `$SessionData` values as the boot images script, and returns a `Zipper.Zpxe.WCFServer.VarDataObject` whose `VarInfo` property is a hash table of variable names and values:

```powershell
param($SessionData)

$VarDataObject = New-Object Zipper.Zpxe.WCFServer.VarDataObject
$variables = @{}
$variables.Add("MyCustomVariable", "TheActualValue")
$VarDataObject.VarInfo = $variables
$VarDataObject
```

The script runs when the device reaches Windows PE, unless 2PXE is integrated with the iPXE Anywhere Web Service (which then provides the variables instead).

## Settings used by the PowerShell request handler

| Setting                                                                                                              | Description                                                                                                                                            |
| -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Allow boot script**, **Boot images**                                                                               | Paths to the two PowerShell scripts.                                                                                                                   |
| **Add variables script**                                                                                             | Path to the add variables script. This setting is only shown for the MEMCM and DeployR integration modes; in PowerShell mode the default path is used. |
| **DefaultMenuItemId**                                                                                                | The menu item selected by default: a boot image key returned by the script, or `exit` (the default) or `reboot`.                                       |
| **EnableMenuCountdown**                                                                                              | How long, in milliseconds, the menu waits before choosing the default item. `0` waits until an item is selected.                                       |
| **AcceptBootKeyEFI**, **AcceptBootKeyBIOS**, **AcceptBootTextEFI**, **AcceptBootTextBIOS**, **iPXEF12PromptTimeout** | The key the user presses to boot from the network, the prompt text, and how long (in milliseconds) to wait for it.                                     |
| **UseEmbeddedBootSDI**                                                                                               | Turn this off if your boot images do not contain `\sms\boot\boot.sdi`.                                                                                 |
| **wimbootParams**                                                                                                    | The wimboot command line.                                                                                                                              |
| **RemoteInstallFolder**                                                                                              | The folder that contains the `Sources` folder.                                                                                                         |

Most of these settings are only shown when **Show advanced** is turned on. See [Configuring 2PXE Server](/2pxe-server/4.0/configuration/2pxe-config-file.md) for descriptions of all settings.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://documentation.2pintsoftware.com/2pxe-server/4.0/configuration/2pxe-config-file/powershell-request-handler.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.