> 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/planning/certificate-considerations.md). # Certificate Considerations {% hint style="danger" %} **Configuration Manager compatibility** Configuration Manager integration is not currently supported by 2PXE Server 4.0. The ConfigMgr-specific certificate guidance on this page is retained for reference only; the general certificate guidance still applies to supported 4.0 configurations. {% endhint %} 2PXE (2Pint Software's build of iPXE) comes pre-built with a limited set of trusted root certificates. This list includes the 2Pint Software CA certificate and the iPXE root CA (public key available here: ). Additionally, by way of cross-signing against the iPXE root CA certificate, the [Mozilla public CA list](#supported-certificate-configurations) is also trusted. Because these CA certificates need to be provided at build time, it is not possible to install your own internal PKI CA certificate as a trusted root CA for the initial bootstrapping of the 2PXE boot process. Additionally, because 2PXE builds are signed by Microsoft, which allows them to be trusted by Secure Boot, 2Pint Software cannot make custom builds of 2PXE that include customer-provided internal PKI CA certificates. ## How 2PXE gets its certificates Starting with 2PXE Server 4.0, 2PXE no longer includes its own certificate authority. Instead, certificates are issued by the 2Pint Software CA through 2Pint Software Online Services, using your license key: * When the **Certificate location mechanism** setting is **Auto**, 2PXE requests an HTTPS certificate for the server's host names from Online Services, and installs the 2Pint Software root CA certificate in the server's trusted root store. The certificate is stored in the local computer personal certificate store, and in `%ProgramData%\2Pint Software\2PXE\Certificates` by default. * When you set a **CustomCAThumbprint**, or when 2PXE runs on a Configuration Manager distribution point that uses HTTPS, the root CA certificate is cross-signed through Online Services so that iPXE trusts it. * If you specify your own certificate by thumbprint or subject name, 2PXE uses it. 2PXE picks up a renewed certificate without a service restart, so choosing **CertificateSubjectName** avoids having to update the configuration each time the certificate is renewed. {% hint style="warning" %} The 2PXE server needs outbound HTTPS access to `https://api.service.2pintsoftware.com` to request and cross-sign certificates. If the server cannot reach it, 2PXE cannot create its certificate, and HTTPS booting will not work until it can. {% endhint %} ## Supported Certificate Configurations {% hint style="info" %} **Note:** While certain certificate configurations may have been tested to work, it is best to keep things simple. For example, while it might work to use a public certificate for 2PXE with a cross-signed PKI certificate for the iPXE Anywhere Web Service, this is a needless complication when a simpler solution (using the public certificate for both services) is available. {% endhint %} In the following table: * ***2PXE Generated*** refers to the certificate issued by the 2PintSoftware.com CA through Online Services when the 2PXE **Certificate location mechanism** setting is **Auto** * ***Cross-Signed Internal PKI*** refers to a certificate issued by a public key infrastructure (PKI) for your organization, whose root CA certificate has been cross-signed by the 2PintSoftware.com CA certificate. See [this link](#supported-certificate-configurations) for a list of supported algorithms for Internal PKI certificates. * ***Non-cross-signed Internal PKI*** refers to a certificate issued by a public key infrastructure (PKI) for your organization, whose root CA certificate has **NOT** been cross-signed by the 2PintSoftware.com CA certificate. * ***Public*** refers to a certificate issued by a publicly trusted certificate authority in the [Mozilla Root CA list](https://wiki.mozilla.org/CA/Included_Certificates).
2PXE (iPXE)iPXE Anywhere Web Service (WS)ConfigMgr (Internal PKI or eHTTPS)DeployR / OtherTested to Work
Any internal PKI CertificateN/AN/AN/A❌*
2PXE Generated or PublicNot installedConfigured (2PXE installed on DP)N/A✅
2PXE Generated or PublicCross-signed Internal PKIN/AN/A❌*
2PXE Generated or Public2PXE Generated or PublicN/A2PXE Generated or Public✅
2PXE Generated or Public2PXE Generated or PublicN/ACross-signed Internal PKI✅**
2PXE Generated or Public2PXE Generated or PublicN/ANon-cross-signed Internal PKI❌
\*Because the iPXE binaries are pre-compiled with limited trusted root certificates, only certificates issued by the 2PintSoftware.com CA (self-generated scenario) or a certificate authority in the [Mozilla Root CA list](https://wiki.mozilla.org/CA/Included_Certificates) can be used to boot iPXE/2PXE \*\*This is a supported scenario but requires modifications to the iPXE WS scripts to download and install the root CA certificate from your Internal PKI. See [#manually-installing-root-ca-certificates-to-ipxe-certificate-store](#manually-installing-root-ca-certificates-to-ipxe-certificate-store "mention") below. ## Example Configurations The following is not an exhaustive list of possible configurations, but rather four of the most common configurations seen in customer environments. ### Public Certificate for All Services This configuration assumes that all services run on the same server and use the same FQDN or CNAME for DNS resolution. Additionally, this assumes that the public certificate has been issued to your server (or a wildcard for your domain) and is installed in the personal store for the local computer. It also assumes that the device that is PXE booting can reach the internet (specifically ). #### 2PXE Settings Set the following values in the **Configure 2PXE** configuration editor (see [Configuring 2PXE Server](/2pxe-server/4.0/configuration/2pxe-config-file.md)), click **Verify** and then **Save**, and restart the "2Pint 2PXE Server" service when prompted: * **External FQDN override** (General settings): should match either the subject or a subject alternative name (SAN) of the public certificate. * **iPXE Anywhere Web Service URI** (iPXE Anywhere Web Service settings): `https://{iPXEAnywhereWebService}:8051` - {iPXEAnywhereWebService} should match either the subject or a subject alternative name (SAN) of the public certificate (and is likely the same value as you set in **External FQDN override**) * **Certificate location mechanism** (HTTPS settings): "CertificateThumbprint" * **Use certificate with specified thumbprint** (HTTPS settings): should match the thumbprint of the public certificate #### iPXE Web Service Settings Edit the following values in the registry under `HKLM\SOFTWARE\2Pint Software\iPXE Anywhere Web Service` and then restart the "2Pint Software iPXE Anywhere Web Service" service: * **HostCertificateThumbprint:** should match the thumbprint of the public certificate #### DeployR Settings Edit the following values in the DeployR Config Editor and then restart the "2Pint Software DeployR Service": * **Certificate location mechanism:** "CertificateThumbprint" * **Certificate thumbprint:** should match the thumbprint of the public certificate ### 2PXE Generated for All Services This configuration assumes that all services run on the same server and use the same FQDN or CNAME for DNS resolution. #### 2PXE Settings Set the following values in the **Configure 2PXE** configuration editor (see [Configuring 2PXE Server](/2pxe-server/4.0/configuration/2pxe-config-file.md)), click **Verify** and then **Save**, and restart the "2Pint 2PXE Server" service when prompted: * **External FQDN override** (General settings): should match the FQDN of the server as you wish it to be presented to connecting clients * **Certificate location mechanism** (HTTPS settings): "Auto" After saving these values and restarting the "2Pint 2PXE Server" service, a 2PXE generated certificate is created and stored in the local computer personal certificate store (as well as `%ProgramData%\2Pint Software\2PXE\Certificates` by default). You need to get the thumbprint for this certificate for use in later values:
#### iPXE Web Service Settings Edit the following values in the registry under `HKLM\SOFTWARE\2Pint Software\iPXE Anywhere Web Service` and then restart the "2Pint Software iPXE Anywhere Web Service" service: * **HostCertificateThumbprint:** should match the thumbprint of the 2PXE generated certificate (captured above) #### DeployR Settings Edit the following values in the DeployR Config Editor and then restart the "2Pint Software DeployR Service": * **Certificate location mechanism:** "CertificateThumbprint" * **Certificate thumbprint:** should match the thumbprint of the 2PXE generated certificate (captured above) ### 2PXE Generated for 2PXE/WS, PKI For DeployR/Other This configuration assumes that all services run on the same server and use the same FQDN or CNAME for DNS resolution. This configuration also assumes that you wish to use a PKI certificate for the DeployR service instead of the 2PXE generated certificate. #### 2PXE Settings Set the following values in the **Configure 2PXE** configuration editor (see [Configuring 2PXE Server](/2pxe-server/4.0/configuration/2pxe-config-file.md)), click **Verify** and then **Save**, and restart the "2Pint 2PXE Server" service when prompted: * **External FQDN override** (General settings): should match the FQDN of the server as you wish it to be presented to connecting clients * **Certificate location mechanism** (HTTPS settings): "Auto" * **CustomCAThumbprint** (HTTPS settings, shown when **Show advanced** is turned on): the thumbprint of the internal PKI root CA certificate After saving these values and restarting the "2Pint 2PXE Server" service, a 2PXE generated certificate is created and stored in the local computer personal certificate store (as well as `%ProgramData%\2Pint Software\2PXE\Certificates` by default). You need to get the thumbprint for this certificate for use in later values:
#### iPXE Web Service Settings Edit the following values in the registry under `HKLM\SOFTWARE\2Pint Software\iPXE Anywhere Web Service` and then restart the "2Pint Software iPXE Anywhere Web Service" service: * **HostCertificateThumbprint:** should match the thumbprint of the 2PXE generated certificate (captured above) #### DeployR Settings Edit the following values in the DeployR Config Editor and then restart the "2Pint Software DeployR Service": * **Certificate location mechanism:** "CertificateThumbprint" * **Certificate thumbprint:** should match the thumbprint of the PKI certificate you have issued You also need to add the cross-signed certificate that is generated from the **CustomCAThumbprint** value to your PXE boot process. See [Manually Installing Root CA Certificates to iPXE Certificate Store](#manually-installing-root-ca-certificates-to-ipxe-certificate-store) for that setup. ### 2PXE integration with ConfigMgr (SCCM) and eHTTPS/PKI {% hint style="danger" %} **Configuration Manager compatibility** Configuration Manager integration is not currently supported by 2PXE Server 4.0. The ConfigMgr-specific certificate guidance on this page is retained for reference only; the general certificate guidance still applies to supported 4.0 configurations. {% endhint %} This configuration assumes that the 2PXE server runs on a distribution point and the ConfigMgr environment is set up for HTTPS or eHTTPS mode. This is not a complete list of the configuration necessary for the 2PXE integration with ConfigMgr, just the relevant certificate configuration. #### 2PXE Settings Set the following values in the **Configure 2PXE** configuration editor (see [Configuring 2PXE Server](/2pxe-server/4.0/configuration/2pxe-config-file.md)), click **Verify** and then **Save**, and restart the "2Pint 2PXE Server" service when prompted: * **External FQDN override** (General settings): should match the FQDN of the server as you wish it to be presented to connecting clients * **Certificate location mechanism** (HTTPS settings): "Auto" to use the 2PXE generated certificate, or "CertificateThumbprint" with **Use certificate with specified thumbprint** set to the thumbprint of a certificate that meets one of the following criteria: * Is the 2PXE generated certificate (same thumbprint as used by 2PXE) * Is a certificate signed by a publicly trusted root CA * **Integration mode** (General settings): "MEMCM", so that 2PXE gathers and cross-signs the relevant certificates from the distribution point * **ConfigMgr certificate authority thumbprint** (ConfigMgr settings, shown when **Show advanced** is turned on): in most cases will be empty, except when using public certificates with ConfigMgr, in which case it should be the thumbprint of the root CA certificate that issued the certificate for the distribution point After saving these values and restarting the "2Pint 2PXE Server" service, a 2PXE generated certificate is created and stored in the local computer personal certificate store (as well as `%ProgramData%\2Pint Software\2PXE\Certificates` by default). You need to get the thumbprint for this certificate for use in later values:
#### iPXE Web Service Settings Edit the following values in the registry under `HKLM\SOFTWARE\2Pint Software\iPXE Anywhere Web Service` and then restart the "2Pint Software iPXE Anywhere Web Service" service: * **HostCertificateThumbprint:** should match the thumbprint of a certificate that meets one of the following criteria: * Is the 2PXE generated certificate (same thumbprint as used by 2PXE) * Is a certificate signed by a publicly trusted root CA ## Manually Installing Root CA Certificates to iPXE Certificate Store For an HTTPS call to be supported anywhere in your 2PXE boot process, the certificate presented by the web server must be signed by a root certificate trusted (signed or cross-signed) by the 2Pint Software CA or iPXE root CA certificates or signed by the 2Pint Software CA certificate itself (the "self-generated" scenario above). When using a certificate authority that is not trusted by 2PXE by default, the root CA must be imported into the iPXE certificate store. This is accomplished in an iPXE script using the [iPXE certstore](#supported-certificate-configurations) command. To enable booting or downloading of content from a server that uses an internal PKI certificate for HTTPS communication, the root CA certificate thumbprint must be configured in the **CustomCAThumbprint** setting in the **Configure 2PXE** configuration editor (HTTPS settings, shown when **Show advanced** is turned on). This generates the necessary cross-signed certificate which can be downloaded to the device during the boot process from 2PXE at the following URL: `https://`***`{2PXEFQDN}`***`/2PXE/Certificate/RootCA.crt` After configuring the `CustomCAThumbprint` value and restarting the 2PXE service, you should validate that the cross-signed certificate has been generated. By default, this certificate is stored at `%ProgramData%\2Pint Software\2PXE\Certificates\CrossSignedCert.crt`. Once you have validated the cross-signed certificate has been generated, you must then add the following lines to your `iPXEboot.ps1` file, or anywhere in your iPXE Anywhere Web Service scripts before you make a call to download from an HTTPS endpoint that uses a certificate issued by the internal PKI: ``` $Paramdata certstore `${pxeurl}2PXE/Certificate/Cross.crt##params=paramdata ``` For example:
--- # 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/planning/certificate-considerations.md?ask=&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.