Skip to main content

1E 23.11 (SaaS)

Peer copy over HTTP or HTTPS

Nomad peer-to-peer content transfer uses SMB by default, which requires File and Print services to be enabled in order for it to share the content. For better security Nomad can be configured to use HTTP or HTTPS for peer-to-peer content transfer, removing the requirement for file shares. When Nomad is configured to use HTTP/S, if Peer Backup Assistant is enabled it will also use HTTP/S.

For some example deployment scenarios and how you can monitor those deployments using the Nomad app refer to:

Enabling HTTP/HTTPS

Enabling HTTP/S for peer-to peer content transfer (including Peer Backup Assistant) is done by modifying the relevant bits of theP2PEnabled registry value as shown in the following table:

Bit

Hex

Decimal

P2P Protocol used

0

0x01

1

SMB

5

0x20

32

HTTP

6

0x40

64

HTTPS

Note

P2PEnabled is a numeric value where, when represented in binary, each bit represents a configurable option, The table above only shows the bits that are relevant to P2P protocol selection. These values can be combined with other P2P settings, refer to P2PEnabled for full details.

It is important to ensure all clients are configured to use the same protocol, as a mismatch in protocol will prevent Nomad peers copying content from the elected master. You can enable multiple protocols on a client - for example P2PEnabled = 0x61 enables the peer to connect to the elected master using either HTTPS, HTTP or SMB. In this scenario, the peer will attempt the most secure protocol (HTTPS) first, followed by HTTP and finally falling back to SMB if it is unable to connect using HTTPS or HTTP.

HTTP and HTTPS Ports

When you enable HTTP and/or HTTPS, by default Nomad will use port 5080 for HTTP and 5443 for HTTPS, If these ports are already in use in your environment, you can define custom port numbers using the following registry values,

Registry value

Default value

Notes

P2PHttpPort

5080

Default HTTP port to use for peer copy. If you are using a custom port, ensure that all Nomad clients use the same custom port.

P2PHttpsPort

5443

Default HTTPS port to use for peer copy. If you are using a custom port, ensure that all Nomad clients use the same custom port.

Client authentication

Client authentication is required when Nomad peers connect to the elected master. Nomad supports two client authentication methods,Windows authentication and certificate-based authentication.

Windows authentication

By default, Nomad peers use the local SMSNomadP2P& account, which is created by Nomad on each client, to authenticate with the elected master (when the master is elected, it shares a key that enables them to determine the credentials for this local account on the master). This requires each client to allow their local SMSNomadP2P& account to access the computer from the network. Alternatively, Nomad peers can be configured to use their Computer Account to authenticate with the elected master using the SpecialNetShare setting. If the Computer Account is used, the Domain Computers group at a minimum must be configured to access the computer from the network on all clients.

By default, the elected Nomad master will allow connections from its own SMSNomadP2P& account and all authenticated Users (Authenticated users is required when using the peer's Computer Account to authenticate). You can restrict this further to just the SMSNomadP2P& account using the AuthenticatedUsers setting.

Certificate-based authentication

When Nomad is configured to use HTTPS for peer-to-peer content transfer, peers can use a PKI Client authentication certificate to authenticate with the elected master. This is more secure than Windows authentication as it does not require any local accounts to be granted 'Access this computer from the network' permissions. To enable certificate-based client authentication:

  • Configure clients to use HTTPS for peer-to-peer content transfer through the P2PEnabled client setting.

  • Ensure clients have enrolled a client authentication certificate from a PKI in the Local Computer Personal certificate store. (Self-signed certificates cannot be used for client authentication). If you are using Configuration Manager with HTTPS site systems, you should already have a suitable PKI client authentication certificate enrolled on all CM clients that Nomad can use for P2P client authentication.

  • Optionally (but recommended) configure CertIssuer client setting to assist Nomad in selecting the correct client authentication certificate if there are several in the Local Computer Personal certificate store

  • Configure P2PSslSettings to enable certificate-based client authentication. When this option is enabled, Nomad does not create the local SMSNomadP2P& account.

Warning

If you enable certificate-based authentication for peer-to-peer content transfer, you must ensure that a valid client authentication certificate is available at all times. If the certificate expires, Nomad will return ERROR_CLIENT_CERT_MISSING (0X209A). This error code has been added to the Nomad SuccessCodes default setting, which means that Nomad will fail the download job and CM will not fall back to BITS to download the content from the DP. Nomad will not be able to download any content until a valid certificate becomes available on the client.

If you have configured Nomad to use a PKI certificate for server or client authentication, when Nomad starts it will look for an appropriate certificate in the Local Computer Personal certificate store. In most cases Nomad will be able to select an appropriate certificate without any additional configuration. In some cases you may need to specifyCertIssuerand possiblyCertSubject.

Client authentication certificate selection

Nomad will select a client authentication certificate for peer-to-peer authenticationfrom the Local Computer Personal certificate store using the following criteria if:

  1. If the first certificate is issued by one of the issuers specified in CertIssuer but the next certificate is not, then the first will be selected. If both match or do not match the CertIssuer, then the next step is evaluated.

  2. If the first certificate has a subject specified in CertSubject but the next is not, then the first will be selected, otherwise the next step is evaluated.

  3. If the first certificate has a subject specified as an FQDN and the second does not, the first will be selected, otherwise the next step is evaluated.

  4. The certificate with the latest expiry will be chosen.

Nomad will select the first certificate that matches the above criteria. CertIssuer should only be required if the CM client is using a self-signed certificate for client authentication with CM site systems and there are certificates from multiple Certificate Authorities. When CertIssuer is defined, Nomad will select the first certificate issued by that CA that matches the other criteria.

Note

Nomad also requires a client authentication certificate for authenticating with CM HTTPS Site Systems. In most cases, it will use the same certificate for authentication with peers and CM site systems, which will typically be the PKI-issued CM client authentication certificate.

If for any reason a different certificate should be used for authentication with CM site systems, you can additionally specify CertSubject.

Caching of certificates

Once a certificate is selected using the above criteria, it is cached and is provided for any subsequent client certificate requests until the certificate is expired or no longer present in store. Once the certificate is expired or no longer present, another certificate is chosen by using the above selection criteria.

Exception

If the registry value "thumbprint" is specified under HKLM\Software\1E\NomadBranch\Platform then the certificate with this thumbprint will be chosen (if it is valid, if not then the above selection criteria is used) if the download URL is a background channel URL or if both registry values CertIssuer and CertSubject are not specified.

Missing or invalid client authentication certificate

If Nomad is unable to select a valid client authentication certificate for any reason (for example if no certificate present, or is expired, or the certificate is not from the specified issuer), then Nomad returns ERROR_CLIENT_CERT_MISSING(0x209A) for the download job. This error code is included in the default SuccessCodes, so if it occurs, Configuration Manager will not revert to downloading using BITS, thereby protecting the network from potential congestion.

  • In Windows PE, Nomad fails the job immediately.

  • In the full OS, Nomad retries every 10 minutes until a valid client certificate is available in the Local Computer Personal certificate store or timeout (defined by P2PClientCertWaitPeriodMins, 24 hours by default) occurs.

    • If a client certificate becomes available before timeout occurs, a new election is initiated and Nomad tries downloading the content again.

    • If no certificate becomes available within the timeout period, Nomad will fail the job.

    • During the timeout period, if the Nomad service is reset, the download job is paused or the system goes to sleep, Nomad will continue to wait for the timeout period to expire. Any other interruption (the for example, if Nomad service is stopped, or the download job is cancelled or expires) will cause the download job to fail with the appropriate error condition.

    • While the download job is waiting for a valid client certificate, Nomad will not process any other download jobs.

Server authentication

Server authentication is required when Nomad is configured to use HTTPS for peer-to-peer content transfer. In this scenario, Nomad binds a server authentication certificate to the HTTPS endpoint to secure the communication between the elected master and peers. This certificate can be generated either by Nomad (self-signed) or through a Public Key Infrastructure (PKI). Use the P2PSslSettings to configure Nomad to use either self-signed (default) or PKI certificate.

Server authentication certificate selection

Nomad will select a server authentication certificate in the Local Computer Personal certificate store using the following criteria

  • Store = MY (the default certificate store)

  • Usage = Server Authentication

  • Subject/DNS = Host name or FQDN

  • Valid (NotBefore is in the past) and not expired (NotAfter is in the future)

  • Issuer = CertIssuer (Optional).

In most cases, the built-in criteria are sufficient to determine a single applicable certificate. If multiple certificates are likely to match these criteria, you can optionally specify CertIssuer to limit the certificates that Nomad will consider to those issued by one or more specific Certificate Authorities. Note that CertIssuer also affects the selection of the Client Authentication certificate. If the server and client authentication certificates are issued by different Certificate Authorities, you can specify multiple CAs with CertIssuer, either using a sub-string that is common to the desired CA names, or a comma-separated list of CA names.

If multiple certificates match the criteria above, Nomad uses the following order of precedence when matching the Subject Name:

  • Hostname and FQDN

  • Hostname

  • FQDN

If a single certificate matching the criteria still cannot be resolved, the matching certificate with the longest validity is used.

Note

  • When using Net literal names (3rd bit in P2PEnabled is set), clients ignore mismatch in host names during the SSL handshake – this is because IP addresses are generally not included in certificates

  • When using self-signed certificates for server authentication, clients do not validate the certificate issuer since it is issued by NomadBranch and it is not a valid CA

  • Due to the nature of how proxy servers can be implemented, some of which can be quite complex, you may need to consult your networking specialist to see if exceptions need to be added to enable Nomad’s peer-copy over HTTP or HTTPS.

Firewall exceptions

Depending on your preferences (protocols, ports) during installation, the installer will add the exceptions to Windows firewall.

Note

If for some reason these exceptions are removed post-installation, Nomad service will automatically re-add them. You'll just have to restart the service. Nomad service checks and fixes required firewall exceptions whenever it starts.

You can verify these in its Inbound Rules:

  1. For HTTPS (port 5443)

    Verifying inbound rules for port 5443
  2. For HTTP (port 5080)

    Verifying inbound rules for port 5080

Note

Firewall exceptions are added against the program "system" not NomadBranch.exe. This is because Nomad uses Windows HTTP Server API (https://docs.microsoft.com/en-us/windows/win32/http/http-api-start-page?redirectedfrom=MSDN)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 an 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.

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 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.

230734692.png
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:

  1. 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.

  2. Enable HTTPS (Bit 6 - 0x0040) in P2PEnabled.

  3. Update CertIssuer with the name of the certificate authority.

  4. P2PSslSettings set to 1 to enable PKI certificate for server authentication.

  5. 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, as shown in the example opposite.

Checking the status of your P2P HTTP server

Alternatively, run NETSH to check the status of the P2P HTTP server, as shown in the example opposite.

Checking the status of the HTTP server using NETSH
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, as shown in the example opposite.

Checking the status of your certificate bindings

Alternatively, run NETSH to check the bindings for the certificates. In our example, the bindings for port 5443 are shown in the example opposite.

Checking certificate bindings with NETSH
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.

In our example, the log illustrates that HTTPS had not been enabled on the PC1 master.

Protocol not enabled on the master

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.

Unknown CA for the certificate

Where errors like this occurs, check the following on master:

  • Expiry date

  • Subjects – should contain hostname or its FQDN

  • Issuer must be trusted via the trust chain on the peer machine

  • SSL Binding – ensure it exists for the HTTPS port.