> 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/ipxe-ws/4.0/configuration/configuring-the-ipxe-web-service.md).

# Configuring the iPXE Web Service

{% hint style="danger" %}
**Configuration Manager compatibility**

Configuration Manager integration is not currently supported by 2PXE Server 4.0. The ConfigMgr-related settings and examples on this page do not provide native Configuration Manager PXE integration with 2PXE Server 4.0.
{% endhint %}

iPXE Anywhere Web Service 4.0 changes how the web service is configured. Earlier versions kept some settings in the `<appSettings>` section of the **iPXEAnywhere.Service.exe.config** file, and others (such as the license key, ports and database connection) in the registry. Starting with 4.0, the `.config` file is no longer used. All settings are stored in the registry under `HKEY_LOCAL_MACHINE\SOFTWARE\2Pint Software\iPXE Anywhere Web Service`, and you change them with the **Configure iPXE WS** configuration editor.

The configuration editor:

* Shows every supported setting, with its current value, grouped by area.
* Hides settings that do not apply to your configuration. For example, the StifleR settings only appear when **Use Infrastructure** is turned on.
* Validates values (required fields, URLs, port numbers, certificate thumbprints, and so on) before they are saved.

{% hint style="warning" %}
Do not edit the iPXE Web Service registry values directly. Use the configuration editor so that values are validated before they are saved.
{% endhint %}

{% hint style="warning" %}
In-place upgrades from iPXE Anywhere Web Service 3.x are not supported. To move from 3.x to 4.0, make a copy of the **iPXEAnywhere.Service.exe.config** file and the registry settings, uninstall 3.x, install 4.0, and then set the values that you need in **Configure iPXE WS**. The [Settings that changed from 3.x](#settings-that-changed-from-3.x) table shows where each old setting moved. See Upgrading to iPXE Anywhere Web Service 4.0.
{% endhint %}

## Opening the configuration editor

The installer adds a **Configure iPXE WS** shortcut to the Start menu, in the **2Pint Software** folder. The shortcut runs the configuration editor, which is installed in the **TwoPint.ConfigEditor.Wpf** folder inside the iPXE Web Service installation folder:

```
"C:\Program Files\2Pint Software\iPXE AnywhereWS\TwoPint.ConfigEditor.Wpf\TwoPint.ConfigEditor.Wpf.exe" TwoPint.iPXEAnywhere.Configuration.editor
```

The editor also opens automatically at the end of a manual installation, as long as the **Launch Configuration Editor** checkbox on the **Completed** page of the installer is selected.

Run the editor as a local administrator, because it writes to `HKEY_LOCAL_MACHINE` and manages the **2Pint Software iPXE Anywhere Web Service** service.

## Using the configuration editor

1. Open **Configure iPXE WS** from the Start menu.
2. Review the settings in each section. Only the most commonly used settings are shown by default. To see all of the settings, turn on the **Show advanced** toggle.
3. Change the settings that you need. Some settings show or hide other settings. For example, choosing a **SQL Server configuration method** shows only the database settings for that method, and the **Certificate location mechanism** controls which certificate settings are shown.
4. Click **Verify** to check the configuration. Fix any values that are flagged as invalid or missing.
5. Click **Save** to save the configuration. If you are prompted to restart the **2Pint Software iPXE Anywhere Web Service** service, click **Yes**. Changes do not take effect until the service restarts.

## Licensing

The iPXE Web Service is licensed with a license key, entered in the **License key** setting (General settings). The iPXE Web Service license key is different from the 2PXE Server license key.

The service checks the license key each time it starts. If the key is valid, an event with the licensed company and expiry date is written to the event log. If the key is missing, invalid or has expired, an event is written to the event log and the service stops. See [Licensing](/ipxe-ws/4.0/operations/licensing.md) for how to update the license key.

## Settings reference

The tables below list the settings shown by the configuration editor, grouped by the section they appear in. Settings marked **Advanced** are only shown when **Show advanced** is turned on.

### General settings

| Setting                                                                                  | Default                                          | Description                                                                                                                                                                                                                                                                                                                                         |
| ---------------------------------------------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **License key** (`LicenseKey`)                                                           | Empty                                            | The iPXE Web Service license key. The service checks it when it starts, and stops if it is missing, invalid or expired (see [Licensing](#licensing)). The license key is also used to request the HTTPS certificate from 2Pint Software Online Services when the **Certificate location mechanism** is **Auto**.                                    |
| **External FQDN Override** (`ExternalFQDNOverride`)                                      | Empty                                            | Overrides the host name used for the web service's HTTPS certificate and for the address it registers with the StifleR infrastructure service. When empty, the server's FQDN is used; on a Configuration Manager distribution point, the distribution point's FQDN (or its internet FQDN, for an internet-only distribution point) is used instead. |
| **Deploy with label** (`DeployWith`)                                                     | `ConfigMgr`                                      | The name shown in the boot menu generated by the iPXE start script, for example **Deploy with ConfigMgr**. It replaces `$DeployWith` in the script.                                                                                                                                                                                                 |
| **Abandoned time limit (in hours)** (`AbandonedTimeLimitInHours`) — Advanced             | `4`                                              | Boot requests that have not been updated within this time are marked as abandoned. `0` turns this off.                                                                                                                                                                                                                                              |
| **Allow local admin bypass** (`AllowLocalAdminBypass`) — Advanced                        | Off                                              | Allows members of the local Administrators group to call the admin API (on the **Run admin on HTTP port** port) without further authorization. When off, admin calls must come from the StifleR infrastructure service or be authorized by the **User authentication script**.                                                                      |
| **Allow no auth script endpoint** (`AllowNoAuthScriptEndpoint`) — Advanced               | Off                                              | Allows clients to run scripts from the **NoAuthScripts** folder in the installation folder without authentication. Only turn this on if you need it.                                                                                                                                                                                                |
| **App instance name** (`AppInstanceName`) — Advanced                                     | `iPXEAnywhere 1`                                 | Not currently used.                                                                                                                                                                                                                                                                                                                                 |
| **Approved devices request limit** (`ApprovedDevicesRequestLimit`) — Advanced            | `604800` (7 days)                                | How long, in seconds, a device approval remains valid after the device is approved. The device authentication script can override this. See [Authentication](/ipxe-ws/4.0/configuration/authentication.md).                                                                                                                                         |
| **Auto-approve devices** (`AutoApproveDevices`) — Advanced                               | Off                                              | Approves every device automatically, without running the device authentication script. Turn this on to boot devices without authentication. See [Authentication](/ipxe-ws/4.0/configuration/authentication.md).                                                                                                                                     |
| **Certificates path (2PXE)** (`CertificatesFolder`) — Advanced                           | `%PROGRAMDATA%\2Pint Software\2PXE\Certificates` | Where the web service stores the certificates it gets when the **Certificate location mechanism** is **Auto**. Replaces the 3.x `CertificatesPath` setting.                                                                                                                                                                                         |
| **Client settings provider service URL** (`ClientSettingsProviderServiceUri`) — Advanced | Empty                                            | Not currently used.                                                                                                                                                                                                                                                                                                                                 |
| **Delete download time limit (in hours)** (`DeleteDownloadTimeLimitInHours`) — Advanced  | `24`                                             | Download records older than this are rolled up into download summaries, which are used for reporting. `0` turns this off.                                                                                                                                                                                                                           |
| **Enable debug log** (`EnableDebugLog`) — Advanced                                       | Off                                              | Not currently used. The web service writes its logs to Windows event logs, under **Applications and Services Logs** > **TwoPintSoftware** > **iPXEAnywhere.WS**.                                                                                                                                                                                    |
| **Debug log path** (`LogPath`) — Advanced                                                | `%PROGRAMDATA%\2Pint Software\iPXEWS`            | The folder for the log file written when the service executable is run interactively from a console, for troubleshooting. Replaces the 3.x `DebugLogPath` setting.                                                                                                                                                                                  |
| **Enable remote console** (`EnableRemoteConsole`) — Advanced                             | Off                                              | Turns on the remote console, web pages that let you connect to an iPXE client while it boots and run commands on it, and the TLS syslog server that it uses (see [Syslog](#syslog)).                                                                                                                                                                |
| **Encryption key** (`EncryptionKey`) — Advanced                                          | A built-in 32-character value                    | Used to encrypt the tokens given to approved devices, so that they survive service restarts, and so that servers in a cluster or load-balanced group can read each other's tokens. Must be exactly 32 bytes when converted to UTF-8. Use the same value on every server in a load-balanced group.                                                   |
| **Request status lifetime (in days)** (`RequestStatusLifetimeLengthInDays`) — Advanced   | `90`                                             | Boot request records older than this are deleted from the database. `0` turns this off.                                                                                                                                                                                                                                                             |
| **Run on HTTP port** (`RunOnHttpPort`) — Advanced                                        | `8051`                                           | The port used by iPXE clients and 2PXE Server to reach the web service. Uses HTTPS when **Use HTTPS** is turned on. The service creates the **2Pint Software iPXE WebService iPXE endpoint - HTTP(s)** firewall rule for this port when it starts.                                                                                                  |
| **Run admin on HTTP port** (`RunAdminOnHttpPort`) — Advanced                             | `8052`                                           | The port used by the admin API, for example by the StifleR infrastructure service. The service creates the **2Pint Software iPXE WebService Admin endpoint - HTTP(s)** firewall rule for this port when it starts.                                                                                                                                  |
| **Token length** (`TokenLength`) — Advanced                                              | `10`                                             | The length of the token used to connect to a client in the remote console.                                                                                                                                                                                                                                                                          |
| **Remote console HTTP URL** (`RemoteConsoleHttpUrl`) — Advanced                          | `http://localhost:8051`                          | The address of the remote console when **Use HTTPS** is turned off.                                                                                                                                                                                                                                                                                 |
| **Remote console HTTPS URL** (`RemoteConsoleHttpsUrl`) — Advanced                        | `https://localhost:8051`                         | The address of the remote console when **Use HTTPS** is turned on.                                                                                                                                                                                                                                                                                  |
| **Base error URL** (`BaseErrorUrl`) — Advanced                                           | `http://ipxe.org/err/`                           | The start of the link to the description of an iPXE error. The error code is added to the end of it.                                                                                                                                                                                                                                                |
| **Pic base error URL** (`PicBaseErrorUrl`) — Advanced                                    | `http://b800.org/`                               | Not currently used.                                                                                                                                                                                                                                                                                                                                 |

### Database settings

The web service stores information about booting devices and their requests in a SQL Server database. The service creates the database, or updates it to the current version, when it starts. See [Permissions](/ipxe-ws/4.0/planning/permissions.md) for the SQL Server permissions needed.

| Setting                                                       | Default                                                                                                            | Description                                                                                                                                                                                                                           |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **SQL Server configuration method** (`SqlConnectionBy`)       | `ServerInstanceAndDB`                                                                                              | How the web service connects to its database. **ServerInstanceAndDB** builds the connection string from the instance and database name below, using Windows authentication. **Advanced** uses the full connection string you specify. |
| **SQL Server instance** (`ConnectionInstance`)                | `.`                                                                                                                | The SQL Server that hosts the database, in the form `server` or `server\instance`. Use `.` for the local computer. Shown for **ServerInstanceAndDB**.                                                                                 |
| **SQL Server database** (`ConnectionDB`)                      | `iPXEAnywhere`                                                                                                     | The database name. To keep using an iPXE Anywhere 3.x database, enter its name (typically `iPXEAnywhere35`). Shown for **ServerInstanceAndDB**.                                                                                       |
| **SQL Server connection string** (`AdvancedConnectionString`) | `Server=.;Database=iPXEAnywhere;Trusted_Connection=True;MultipleActiveResultSets=true;TrustServerCertificate=True` | A full .NET SQL connection string. Use this to specify a port or other connection options. Shown for **Advanced**.                                                                                                                    |

### HTTPS settings

| Setting                                                                             | Default        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ----------------------------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Use HTTPS** (`RunOnHttps`)                                                        | On             | Controls whether the web service uses HTTPS. When turned off, the certificate settings are hidden.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| **Certificate location mechanism** (`CertificateLocateBy`)                          | `Auto`         | How the web service finds the certificate to bind to its HTTPS ports. **Auto** requests a certificate for the server's host name (see **External FQDN Override**) from 2Pint Software Online Services, using the license key, and installs the 2Pint Software root certificate. **CertificateThumbprint** uses the certificate with the thumbprint you specify. **CertificateSubjectName** uses the certificate with the subject name you specify, which avoids having to update the configuration each time the certificate is renewed. Renewed certificates are used without restarting the service. |
| **Use certificate with specified thumbprint** (`HostCertificateThumbprint`)         | Empty          | The thumbprint (40 hexadecimal characters) of the certificate to use. Shown when the location mechanism is **CertificateThumbprint**.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| **Use certificate with specified subject name (CN)** (`HostCertificateSubjectName`) | Empty          | The subject name (CN) of the certificate to use. Shown when the location mechanism is **CertificateSubjectName**.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| **HTTPS certificate store name** (`HostCertificateStoreName`)                       | `My`           | The certificate store that contains the certificate. Not used when the location mechanism is **Auto**.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| **HTTPS certificate store location** (`HostCertificateStoreLocation`)               | `LocalMachine` | The location of the certificate store. Not used when the location mechanism is **Auto**.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |

### Scripts

These PowerShell scripts control how the web service responds to each type of request. Relative paths are relative to the iPXE Web Service installation folder (by default `C:\Program Files\2Pint Software\iPXE AnywhereWS`), so the default scripts are in its **Scripts** folder; full paths can also be used. If a script does not exist, an error is written to the event log and the request fails. See Updating the Scripts Folder.

| Setting                                                                      | Default                                           | Description                                                                                                                                                                                                |
| ---------------------------------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **iPXE start script** (`IPxeStartScript`) — Advanced                         | `Scripts\Boot\iPXEboot.ps1`                       | Generates the iPXE script returned for a boot request from 2PXE Server (the **BootRequest** feature).                                                                                                      |
| **iPXE config script** (`IPxeConfigScript`) — Advanced                       | `Scripts\config\iPXEconfig.ps1`                   | Returns configuration for a device during an ongoing boot (the **Config** feature).                                                                                                                        |
| **iPXE config inject file script** (`IPxeConfigInjectFileScript`) — Advanced | `Scripts\config\iPXEinjectfile.ps1`               | Returns extra files to inject into the boot image (the **ExtraFile** feature).                                                                                                                             |
| **Success logs scripts** (`SuccessLogsScript`) — Advanced                    | `Scripts\Logs\SuccessLogsScript.ps1`              | Not currently used.                                                                                                                                                                                        |
| **Device authentication script** (`DeviceAuthenticationScript`) — Advanced   | `Scripts\Authentication\DeviceAuthentication.ps1` | Decides whether a device is approved to boot, for example by prompting for a PIN. Not used when **Auto-approve devices** is turned on. See [Authentication](/ipxe-ws/4.0/configuration/authentication.md). |
| **User authentication script** (`UserAuthenticationScript`) — Advanced       | `Scripts\Authentication\UserAuthentication.ps1`   | Authorizes calls to the web service and admin API that are not otherwise authorized.                                                                                                                       |
| **WinPeShl script** (`WinPeShlScript`) — Advanced                            | `Scripts\config\WinPEshl.ps1`                     | Returns the WinPEShl.ini content for WinPE (the **WinPEShl** feature).                                                                                                                                     |
| **WinPeStart script** (`WinPeStartScript`) — Advanced                        | `Scripts\config\WinPEStart.ps1`                   | Returns the commands to run when WinPE starts (the **RunCmdLineWinPE** feature).                                                                                                                           |
| **WinPeEnd script** (`WinPeEndScript`) — Advanced                            | `Scripts\config\WinPEEnd.ps1`                     | Returns the commands to run at the end of WinPE (the **RunCmdLineWinPEEnd** feature).                                                                                                                      |
| **Process logs script** (`ProcessLogsScript`) — Advanced                     | Empty                                             | The script that runs when logs are uploaded to the web service. See [Trigger PowerShell Script on Uploaded Logs](/ipxe-ws/4.0/operations/trigger-powershell-script-on-uploaded-logs.md).                   |
| **Failure logs script** (`FailureLogsScript`) — Advanced                     | Empty                                             | Not currently used.                                                                                                                                                                                        |

The features named above are the **Enabled iPXE Anywhere Web Service features** that 2PXE Server sends to the web service. See [Integrating with 2PXE Server](/ipxe-ws/4.0/configuration/integrating-with-2pxe-server.md).

### Syslog

These settings configure the TLS syslog server used by the remote console. It only runs when **Enable remote console** is turned on.

| Setting                                                                  | Default        | Description                                                          |
| ------------------------------------------------------------------------ | -------------- | -------------------------------------------------------------------- |
| **Syslog server address** (`SysLogAddress`) — Advanced                   | `127.0.0.1`    | The IP address the syslog server listens on.                         |
| **Syslog port** (`SysLogPort`) — Advanced                                | `514`          | The port the syslog server listens on.                               |
| **Syslog certificate store** (`SysLogCertificateStore`) — Advanced       | `My`           | The certificate store that contains the syslog server's certificate. |
| **Syslog certificate location** (`SysLogCertificateLocation`) — Advanced | `LocalMachine` | The location of the certificate store.                               |
| **Syslog certificate subject** (`SysLogCertificateSubject`) — Advanced   | Empty          | The subject name of the certificate used by the syslog server.       |

### Infrastructure Settings

| Setting                                                                                                                                        | Default | Description                                                                                                                                                                                                                                                   |
| ---------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Use Infrastructure** (`JoinInfrastructure`)                                                                                                  | On      | Registers the web service with the StifleR infrastructure service, and gets network location information from StifleR for booting devices. The other settings in this section are only shown when this is turned on. Turn this off if you do not use StifleR. |
| **StifleR Server API URL** (`StifleRServerApiUrl`)                                                                                             | Empty   | The URL of the StifleR server's API, including the port, for example `https://stifler.contoso.com:9000`. Required when **Use Infrastructure** is on.                                                                                                          |
| **Heartbeat rate online threshold for infrastructure service in seconds** (`ServiceHeartBeatRateSec`) — Advanced                               | `30`    | The maximum time between heartbeats for the infrastructure service to be considered online.                                                                                                                                                                   |
| **Maximal allowed time difference in infrastructure service calls in seconds** (`MaxTimeDifferenceAllowedInInfrastructureCallsSec`) — Advanced | `60`    | The maximum clock difference allowed between the infrastructure service and this server.                                                                                                                                                                      |
| **PlatformR token expiration time in minutes** (`PlatformRTokenExpirationMinutes`) — Advanced                                                  | `2`     | How long infrastructure tokens are valid, from 1 to 60 minutes.                                                                                                                                                                                               |

## Settings that changed from 3.x

Most settings keep the same name they had in 3.x. The following settings were renamed, combined or removed:

| 3.x setting                            | 4.0 setting                                                                                                                |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `iPXEAnywhere.Service.exe.config` file | Registry, managed with **Configure iPXE WS**                                                                               |
| `Port` (registry), `RunonHttpPort`     | **Run on HTTP port** (`RunOnHttpPort`)                                                                                     |
| `AdminPort` (registry)                 | **Run admin on HTTP port** (`RunAdminOnHttpPort`)                                                                          |
| `ConnectionString` (registry)          | **SQL Server configuration method**, **SQL Server instance**, **SQL Server database** and **SQL Server connection string** |
| `HostCertificateThumbprint`            | **Certificate location mechanism** and **Use certificate with specified thumbprint**                                       |
| `CertificatesPath`                     | **Certificates path (2PXE)** (`CertificatesFolder`)                                                                        |
| `DebugLogPath`                         | **Debug log path** (`LogPath`)                                                                                             |
| `StifleRURL`                           | **Use Infrastructure** and **StifleR Server API URL**                                                                      |
| `EnableSyslogServer`                   | **Enable remote console** (the syslog server runs with the remote console)                                                 |


---

# 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/ipxe-ws/4.0/configuration/configuring-the-ipxe-web-service.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.
