> 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/stifler/features-breakdown/client-leader-roles.md). # Client Leader roles To facilitate maximum peering efficiency and bandwidth control, the StifleR Server dynamically assigns client leader roles to various clients within managed networks. There are three leader roles: * **Red Leader** – manages content downloads over the WAN. * **Blue Leader** – manages content transfer requests between networks (subnets). * **Green Leader** – a client role which can function as a hosted cache server. #### Leader ports at a glance {% hint style="info" %} StifleR reconfigures Windows BranchCache to use **TCP 1337** for standard peer-to-peer content transfer, in place of the native Windows default of **TCP 80**. The ports below build on that base port and are specific to StifleR's leader roles. {% endhint %}
PortProtocolUsed by / for
1337TCPStandard peer-to-peer (Distributed Mode) content transfer between clients.
1338TCPBlue Leader — proxies content requests across subnet boundaries (one port above the standard 1337).
1339TCPGreen Leader / Hosted Cache mode — content requests to a client acting as a hosted cache server.
3702UDPWS-Discovery peer and content probes (native BranchCache discovery mechanism).
3703UDPBlue Leader to Blue Leader — bridges multicast probes across subnet boundaries.
*** ## Red Leader A Red Leader is a role which is responsible for managing content transfers over a WAN. One Red Leader is assigned for each subnet. This is a 100% dynamic, automatic process which may change at any time during a download in order to optimize performance. The figure below shows a StifleR environment of 3 subnets, grouped into a Network Group and a single Location, each with Leaders assigned.

A typical StifleR standard setup with Red and Blue Leaders assigned per subnet. Each Red Leader will download the source data and simultaneously share this with its subnet peers.

### Red Leader assignment The Red Leader assignment is completely dynamic and may switch several times during downloads in order to ensure the most efficient usage of WAN and LAN infrastructure. Typically, the first machine in a subnet that connects to the StifleR Server will be assigned as the Red Leader. That Red Leader then remains as Red Leader until a more suitable candidate connects, in which case the new Red Leader is assigned and the old Red Leader gracefully retires into network obscurity. ### Red Leader traffic flow The following visualization depicts the flow between server and client.

Figure above shows traffic flow between StifleR server and clients. (NB. All traffic is UDP based and as such may be lost in transit) StifleR is designed to handle such interruption. *A client will De-Nominate itself when it has been unable to Check In to the Server within the threshold timeout

### When is a new Red Leader re-assigned? StifleR checks and compares the following for each client as part of the assignment process: * If the current Red Leader has not responded to the server within the configured threshold value * This typically occurs where there is a communication breakdown between a nominated Red Leader and the StifleR Server. The Server sends a message to appoint the Red Leader and the Red Leader must confirm the appointment within the threshold time. In case a client cannot be assigned for a Network Group, a warning will be recorded in the Windows Event Log and the Server will move on to the next best nominee. * If the current Red Leader has been marked with the `NotLeaderMaterial` flag set to `True`: * It may be undesirable for certain clients to become Red Leaders, and in such cases this can be configured on the client (by setting the `NotLeaderMaterial` setting value to `1` in the `StifleR.ClientApp.exe.config` file), or scripted on the Server by setting the `NotLeaderMaterial` WMI property on the client instance. * A client with a higher priority job starts * The higher priority job client will become Red Leader. * A client with the same priority but a higher BranchCache version connects to the server * Higher BranchCache version clients will be a preferred Red Leader, as a V2-capable system can utilize deduplication during the download and can also provide a V1 hash to Windows 7 clients. * If a client connects that has downloaded more than the other clients over a configured threshold (10% more) * If the newly connected client holds more than 10% of the download in its cache than the current Red Leader, it will become the preferred nominee and be appointed Red Leader. * If we have more data transferred (10% more) and priority is the same or higher and BranchCache version is the same or higher, but uptime is higher * As most machines at the start of a job end up within the same range, this is the most common rule that applies. Most Red Leaders have a high uptime. ### **Generic Red Leader selection example** * Machine1 connects and the StifleR server detects that no other clients are online for that segment. The client is not marked with `NotLeaderMaterial`, so it will be selected as Red Leader. Machine1 is not currently transferring any active jobs (Windows Service Mode). * Machine4 connects on the same segment. It is transferring a low-priority job and will be assigned as Red Leader. The Server assigns Machine4 to be Leader and retires Machine1. * Machine5 connects and is transferring the same job as Machine4. Machine5 has a higher uptime, which will rank it higher than Machine4, but it has also transferred roughly as much as Machine4. Machine4 stays as Red Leader, but Machine5 gets a BITS policy that stops it from actively transferring any large amount of data. Machine4 gets the high-bandwidth transfer throttle value defined for that subnet. * Machine6 comes online and is transferring a high-priority job. Machine6 becomes the new Red Leader, and the downloads for Machine4 and Machine5 are then stopped as both receive a low BITS policy value. * Machine7 comes online and has a higher BranchCache version (Windows 10 = V2) than the others (Windows 7 = V1). As Machine7 is also downloading this high-priority job, even though it has transferred less than Machine6, it is assigned Red Leader. * After Machine6 and Machine7 complete their downloads, Machine5 becomes Red Leader. * As soon as Machine4 and Machine5 complete their downloads, Machine7 becomes the Red Leader as it has the highest BranchCache version. * No client is actively transferring any data, so Machine7 stays the Red Leader. ### **Red Leader selection process high level – visualized** The following section shows a high-level overview of how a Red Leader is used to transfer data and throttle bandwidth. First off, for example, a BITS job is started:

Figure above shows three clients in the same subnet starting the same BITS download at the same time. (Assume same operating system version). Each client connects to the content provider via BITS and checks in to the StifleR server via Stifler Client

Figure above shows three clients in the same subnet, The server chooses the best candidate to be Red Leader and communicates to it directly that it has been appointed Red Leader. Client1 is assigned Red Leader.

When the BITS job starts, the StifleR clients send statistics up to the StifleR server. This provides the server with the information needed to select the best candidate to be Red Leader — in this case, Client 1. As Client 1 downloads, it will share content with the peer clients on the LAN. At the same time, peer clients 2 and 3 are automatically configured to throttle down their WAN BITS download speed, leaving maximum bandwidth to the Content Server available for the Red Leader. Once a leader has been selected, the StifleR server starts to send regular configuration messages to the leader every x (configurable) seconds. The new leader uses these messages to set the (centrally configured) maximum bandwidth through an installed (Microsoft-signed) filter driver. The message also includes flags that change other features such as InterVLAN transfers, BranchCache V1 content generation, etc.

Figure Client 1 has gone AWOL. The server will pick up on this and automatically assign a new Red Leader for the subnet

Each Leader reports up to the StifleR server at a regular interval (tracked as the `LastCheckIn` value). In the event that this communication stops for a period, the StifleR server will automatically mark the failed Red Leader as `NotLeaderMaterial` and assign a new Red Leader to take over the WAN download.

Figure Client 2 is assigned Red Leader. As soon as Client 2 starts downloading data this is picked up by Client 3 which then sources the data from Client 2 using BranchCache

Seamlessly, the other peers will swap sources to continue the download from the new Red Leader. *** ## Blue Leader Blue Leaders are able to communicate with the other Blue Leaders within a [Network Group](/stifler/operations-and-features/overview-and-navigation/network-topology/network-groups.md) to facilitate the sharing of cached content between peers across subnet boundaries at the local level. The Blue Leader role is automatically assigned to a client per subnet. A Blue Leader is basically a Red Leader (assigned using the same selection process), but stripped of the ability to download content over the WAN. This feature requires port 3703 (UDP) to be open for multicast communication from Blue Leaders to clients on the local network segment. All leaders communicate with other leaders on ports 3704 and 3705 (UDP). Also make sure standard BranchCache content traffic on **TCP 1337** is reachable, along with the dedicated **Blue Leader proxy port, TCP 1338** — one port above the standard BranchCache port — which the Blue Leader uses to relay content requests to clients on other subnets. ### When is a Blue Leader not elected? * On Wi-Fi networks, unless specifically overridden. * On subnets with fewer than 5 connected clients — a Green Leader is activated for them instead. ### Blue Leader and Delivery Optimization * Delivery Optimization (DO) uses DNS Service Discovery. * Both Green and Blue Leaders forward DNS-SD to other networks in the same segment, from StifleR 2.11 and above. * This binds DO peers together in Network Groups for smaller downloads. * Blue Leaders do not generate V1 content — only the Red Leaders perform these hash calculations. *** ## Green Leader A Green Leader is a client which can function as a hosted cache server, and which can be manually specified on a template or network group. A Green Leader can be defined by modifying a Template or a Network Group. {% hint style="danger" %} Be aware! If a Green Leader is set on a template, all network groups using that template will use the Green Leader specified. This can cause unwanted traffic over locations with poor connectivity between them. {% endhint %} ### Resulting configuration When a client is configured to be a Green Leader, the client will be configured as follows: * The BranchCache cache size will be configured based on the following rules: * If the disk size is under 128 GB, the BranchCache cache size will be set to 50 GB. * If the disk size is above 128 GB, the BranchCache cache size will be set to 50% of the total disk size. * The `TwoPint.PeerDist.BlueGreenLeader.exe` process will be started. * Standard peer-to-peer content requests continue to use **TCP 1337**, the same port as any other StifleR-managed BranchCache client. * The hosted cache service listens separately on **TCP 1339** for hosted-cache requests from other clients. {% hint style="info" %} 1337 and 1339 are distinct ports serving different purposes: 1337 is the standard BranchCache peer-to-peer port used by every client, while 1339 is specific to a client acting as a Green Leader / hosted cache server. {% endhint %} ### BranchCache mode configuration Depending on what settings are used for the Template/Network Group, the clients may behave differently #### **Distributed mode (Force Hosted Cache mode = Disabled)** If the network group contains multiple networks and the Green Leader is on a different network from the client requesting data, one of the following will occur: * If the network with the Green Leader or requesting client contains 4 or fewer clients, the clients will switch to `Hostedclient` mode and point directly to the Green Leader(s). * If the network with the Green Leader or requesting client contains 5 or more clients, the clients will send normal BC probes, and inter-network connectivity will be handled by the Blue Leader clients. #### **Hosted client mode (Force Hosted Cache mode = Enabled)** In this mode the Green Leader will behave as a Hosted Cache Server. This means the client will store data in its cache and share it with requesting clients. The requesting clients are set to `Hostedclient` mode, and the clients themselves will not save any BC data but rather forward the data to the Green Leader (in the same way as they would have done to a hosted cache server). {% hint style="info" %} The Green Leader can both send and receive data from a BranchCache-enabled WinPE client. {% endhint %} --- # 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/stifler/features-breakdown/client-leader-roles.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.