> 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/3.1/configuration/configuring-a-beacon-server.md). # Configuring a Beacon Server Prior to configuration, a Beacon server must be installed in your environment. See [StifleR Beacon installation](/stifler/3.1/setup/installation/stifler-beacon-installation.md) for more information. *** ## Assigning a Beacon to Network Groups Beacons are assigned within the StifleR Dashboard. Assignments can be made at any\ topology level; StifleR resolves the best beacon for each network group by walking\ the hierarchy: **Network group → Location → Area → Default** The most specific assignment wins. Assign beacons as close as possible to the groups\ they should measure for the most representative results. ### Default beacon Marking a beacon as **Default** makes it the fallback for any network group that has\ no explicit assignment at the network group, location, or area level. A default beacon\ is not required if all groups have direct assignments. *** ## Measurement Priority When a beacon is assigned, you can choose how the measurement result is applied: | Setting | Behaviour | | --------------------------- | ---------------------------------------------------------------------------------------------------------------- | | **Beacon measure priority** | StifleR adjusts the throttle target automatically based on new measurements | | **Template priority** | Measurement results are recorded but the template's fixed values are used for throttling; beacon data is ignored | *** ## Triggering Measurements ### Scheduled (automatic) Measurements run automatically on a configurable schedule. Every 30 minutes the\ StifleR Service scans all network groups and queues those that are due. A group is due\ when it has not been measured within the configured measurement interval (default: 6 days). ### Manual (ad-hoc) Open the relevant network group in the dashboard and click **Measure now** in the\ **Bandwidth and throttling settings** section. Results appear in the Beacons table\ within seconds. Ad-hoc measurements take priority over the scheduled queue. *** ## Server Configuration Settings Open the **Config Editor** for the StifleR Server. ### Bandwidth Settings | Setting | Default | Description | | ---------------------------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------- | | Maximum bandwidth measurement interval in seconds | `518400` (6 days) | How long to wait before re-measuring a network group. Set to `3600` for hourly measurements. | | Maximum bandwidth poll interval between subnets in seconds | `10` | Delay between polling cycles inside the measurement loop. | | Bandwidth Tuning | See note | Beacon measurement must be enabled here. See Bandwidth Tuning. | ### Infrastructure Settings | Setting | Default | Description | | --------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------ | | Heartbeat rate online threshold for infrastructure service in seconds | `30` | A beacon is considered offline if its last heartbeat is older than this value. | > **Both levels required.** Beacon measurement must be enabled in the server-level\ > **Bandwidth Tuning** setting **and** in each network group's own **Bandwidth Tuning**\ > setting. If either is missing, the group is silently skipped. *** ## Beacon Configuration Settings Open the **Config Editor** for the StifleR Beacon. ### Infrastructure | Setting | Default | Description | | ----------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------- | | StifleR Server | *(required)* | Full URL to the StifleR Server API | | Heartbeat frequency for beacon in seconds | `30` | How often the beacon sends its heartbeat and measurement counters to the server | | Beacon preferred FQDN | *(optional)* | Override the hostname the server advertises to clients. Useful when the beacon's DNS name differs from its system hostname. | ### Binding | Setting | Default | Description | | ---------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Port for binding | `5201` | iPerf3 listen port | | Port for ping | `5200` | FastPing (TCP latency) listen port | | IP address for binding | *(auto)* | Leave blank to use the interface that connects to the StifleR Server. Set explicitly if the beacon is multihomed and you need to control which address clients connect to. | | Prefer IPv4 over IPv6 | `true` | When the beacon has both address families, prefer IPv4 | *** ## How to Configure Hourly Measurements 1. Open the Config Editor for the **StifleR Server**. 2. Under **Bandwidth Settings**, set **Maximum bandwidth measurement interval in**\ **seconds** to `3600`. 3. Confirm that beacon measurement is enabled in **Bandwidth Tuning** at the server level. 4. In the dashboard, confirm each target network group also has beacon measurement\ enabled in its own **Bandwidth Tuning** field. 5. Restart the StifleR Service. *** ## Troubleshooting ### No measurements running at all * **Beacon measurement not enabled at server level**: Open the Config Editor and confirm\ beacon measurement is enabled in the server-level Bandwidth Tuning settings. * **Beacon measurement not enabled on the network group**: Each network group has its own\ Bandwidth Tuning field. Both the server and the group must have beacon measurement\ enabled. This is the most common cause of measurements appearing configured but never\ running. * **No beacon assigned**: The network group (or its parent location/area) must have a\ beacon assigned. Groups with no reachable beacon are silently skipped. * **Beacon offline**: The beacon must have sent a heartbeat within the configured\ threshold (default 30 seconds) to be considered online. * **Client capability not enabled**: The bandwidth measurement capability must be\ enabled in the client's feature set. This is on by default for Standard-tier and\ above licensing. ### Measurements less frequent than expected * Check the **Maximum bandwidth measurement interval** setting. The default is 6 days. * The service scans for eligible groups every **30 minutes**. Even with a 1-hour\ interval configured, measurements may lag up to 30 minutes past their due time. * Each network group tracks its own last measurement date. Verify it is being updated\ by checking the group in the dashboard. ### Measurements failing * **Firewall**: TCP 5200 and TCP 5201 must be open inbound on the beacon from all\ client subnets being measured. * **iPerf3 not running**: Check beacon event logs. The beacon restarts iPerf3\ automatically if it stops, but a persistent failure (for example a port conflict)\ will appear in the logs. * **DNS resolution**: The client resolves the beacon's hostname before connecting. If\ DNS fails, it falls back to the registered IP address. --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://documentation.2pintsoftware.com/stifler/3.1/configuration/configuring-a-beacon-server.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.