Contents
Firewall exceptions
Depending on your preferences (protocols, ports) during installation, the installer will add the exceptions to Windows firewall.
You can verify these in its Inbound Rules:
- For HTTPS (port 5443)
- For HTTP (port 5080)
Note that the firewall exceptions are added against the program "system" not NomadBranch.exe. This is because Nomad uses Windows HTTP Server API to create the HTTP server and under this API all requests are handled by Windows kernel's "system" program not by Nomad directly. In some third-party firewalls you may have to use the program name "ntoskrnl.exe", since "system" is actually alias for ntoskrnl.exe.
Windows PE support
When running in Windows PE, Nomad can download content from peers over HTTP/S, but is not able to serve content to others (a Windows PE client will not be elected as a master). However Nomad still needs to be configured correctly (port usage and certificate type) or it will not be able to connect peers.
Certificate-based P2P Client Authentication in Windows PE
When Nomad is configured to use certificate-based client authentication for peer-to-peer content transfer, to support running in Windows PE you will need to update the Windows PE boot image(s) to include a client authentication certificate in the Windows PE boot image (as Windows PE will not be able to enrol a Client Authentication certificate, typically done through Active Directory). If you are using 1E PXE Everywhere and have prepared boot images using UpdateBootImage with a PKI-issued client authentication certificate, no further action is required. If you are not using PXE Everywhere, or have prepared boot images using a CM self-signed certificate you will need to update your boot images to use a PKI-issued Client Authentication certificate.
If CM is using PKI-issued certificates for Client Authentication, you can use (export) the certificate that CM will have already prepared for use with boot images. If CM is using self-signed certificates, you will need to export a suitable PKI-issued Client Authentication certificate. In either case, you will need to export the appropriate certificate and provide the path to the exported certificate in the UpdateBootImage UI / command line. Even if you are not using PXE Everywhere, you can use the UpdateBootImage tool by installing just the PXE Everywhere Admin Tools on a device that has the CM console and Windows 10 ADK (version corresponding to the version of Windows PE you are using for your boot images). You can download PXE Everywhere from the 1E Support Portal.
To find out more about preparing boot images with UpdateBootImage, refer to PXE Everywhere 4.0 - Preparing and deploying the PXE Everywhere boot image.
Certificate-based P2P Client Authentication in the full OS
When a Task Sequence reboots from WinPE into the full OS, Nomad will usually fail to find a certificate in the Microsoft certificate store. This is not an issue. Default logging level logs this fact, but does not show that Nomad successfully gets the BootImage certificate which the Task Sequence had previously stored in its variables list while in WinPE. Nomad uses this BootImage cert to authenticate with peers, and also with the Background Channel proxy to read data from Content Distribution if SSD is enabled and required. The log goes on to show the "Peer Connected OK" and gets the content.
Whilst Nomad Branch and 1E Client are separate services, Nomad depends on 1E Client to post events via the Tachyon Switch. However, the Client connection to the Switch depends on finding a certificate in the Microsoft certificate store, which does not exist, and 1E Client logs this error (not in the Nomad log). The 1E Client is unable to use the BootImage cert that Nomad uses. Inability to post events while the Task Sequence is running is not an issue, and any errors logged should not be of any concern. When the Task Sequence completes, your normal process of certificate enrollment will complete and the 1E Client will connect to the Switch and the backlog of Nomad events will be posted.
Whilst unnecessary, if you want Nomad events to be posted sooner in full OS, you can modify your Task Sequence to enrol a certificate into the Microsoft certificate store earlier. One method is to add a step to enable AutoEnrollment after 1E Client (and Nomad) is installed. For example, a Run command-line:
reg add HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Cryptography\AutoEnrollment /v AEPolicy /d 7 /t REG_DWORD /f /reg:64
Configuring Nomad to to use HTTP/S in Windows PE
Nomad uses a custom Install and configure Nomad in WinPE Task Sequence step to install Nomad after the Task Sequence has booted into Windows PE. The settings highlighted below are related to configuration for HTTP/S.
- P2PEnabled must be set to include HTTP or HTTPS. By default, this is set to 0x9, which disables HTTP/S
- P2PHttpPort is disabled unless HTTP is enabled (bit 0x20 set in P2PEnabled). It defines the port that is used for Nomad P2P communication over HTTP (default 5080)
- P2PHttpsPort is disabled unless HTTPS is enabled (bit 0x40 set in P2PEnabled). It defines the port that is used for Nomad P2P communication over HTTPS (default 5443)
- Use PKI cert for client auth enables certificate-based client authentication, which requires a PKI-issued certificate. Selecting this option sets bit 0x2 of P2PSslSettings
- Use PKI cert for server auth configures Nomad to use a PKI certificate for server authentication when HTTPS P2P is enabled (bit 0x40 set in P2PEnabled). If this option is not checked and bit 0x40 in P2PEnabled is set, Nomad will use a self-signed certificate for server authentication.
Configuring use of PKI-issued certificates post-installation
If Nomad was originally installed to use HTTPS with self-signed certificates for server authentication and you want to switch to using PKI-issued certificates, do the following:
- Deploy the certificate to all Nomad clients. Ensure that the certificate's usage is Server Authentication and the certificate Subject is the client's host name or FQDN.
- Enable HTTPS (Bit 6 - 0x0040) in P2PEnabled.
- Update CertIssuer with the name of the certificate authority.
- P2PSslSettings set to 1 to enable PKI certificate for server authentication.
- Restart the Nomad service.
Checking the status of your Nomad P2P HTTP server
To check the status of the P2P HTTP server:
- Open the NomadBranch log.
- When the Nomad service starts, it logs a list of URLs it listens to,
- Alternatively, run
NETSH
to check the status of the P2P HTTP server:
Checking SSL certificate bindings
To check the bindings of your SSL certificates:
- Open the Nomad log.
- When the Nomad service starts, it logs the name of the certificate and its issuer.
- Alternatively, run
NETSH
to check the bindings for the certificates. In our example, the bindings for port 5443 are:
Troubleshooting failures during HTTP/HTTPS downloads
The most likely causes of HTTP/HTTPS download failures occur during a connection to a master. The most common errors are detailed below:
Error codes | Reason |
---|---|
0x00002efd 0x00004CF | HTTP/HTTPS is not enabled on the master or HTTP/HTTPS server on the master is listening on different port. Possible solution: Double-check the values of P2PEnabled on both the client and remote peer - they should be the same. |
0x00002f8f 0x000000A | Invalid Certificate on master. In our example, issues with certificates causes the download to fail with 0x00002f8f (security error) and the logging does not identify the cause of the failure. Where errors like this occurs, check the following on master:
|