The interactive file manager requires Javascript. Please enable it or use sftp or scp.
You may still browse the files here.

Name	Modified	Size	InfoDownloads / Week
Parent folder
thuBeacon-1.4.2.0-x64-dist.zip	2026-05-03	778.1 kB	4
README.md	2026-05-03	61.0 kB	0
Totals: 2 Items		839.0 kB	4

thuBeacon — Desktop Alert Notification System

thuinformatik GmbH | Version 1.4.2 | .NET Framework 4.7.2

Overview

thuBeacon is a client-server system for pushing scrolling alert banners to desktop workstations. It consists of three components:

Component	Type	Description
thuBeaconServer	Windows Service	Central server — manages customers, locations, tokens, messages, analytics, and agent connections over TLS
thuBeaconAgent	Startup Application (WinExe)	Runs on each workstation, connects to the server, displays banner alerts, and reports analytics
thuBeaconGui	Desktop Application	Admin GUI — manages customers, locations, agents, messages, tokens, and analytics/charts

How It Works

An admin creates alert messages in thuBeaconGui (e.g., "Emergency maintenance at 18:00")
The thuBeaconServer stores the message and schedules delivery based on display time and expiry
Connected thuBeaconAgent instances receive the message and display a scrolling banner at the top of the screen
Banners can be configured with custom colors, font size, scroll speed, and duration
Users can dismiss closable banners; the agent notifies the server when a message is dismissed
thuBeaconAgent periodically submits system analytics (CPU, memory, hardware, OS) to the server
thuBeaconGui displays analytics charts, connection timelines, and maintenance window suggestions
The server can push agent auto-updates to connected agents when a newer version is configured

Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                           NETWORK TOPOLOGY                                  │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│                        ┌──────────────────────┐                             │
│                        │   thuBeacon Server   │                             │
│                        │   (Primary)          │                             │
│                        │                      │                             │
│                        │   TCP/5000 (TLS 1.2) │◄─── Agent + Admin           │
│                        │   TCP/6000 (TLS 1.2) │◄─── HA Replication          │
│                        └──────────┬───────────┘                             │
│                                   │                                         │
│                          HA Sync (TCP/6000)                                 │
│                          HMAC-SHA256 auth                                   │
│                                   │                                         │
│                        ┌──────────┴───────────┐                             │
│                        │   thuBeacon Server   │                             │
│                        │   (Secondary)        │                             │
│                        │                      │                             │
│                        │   TCP/5000 (TLS 1.2) │◄─── Agent + Admin           │
│                        │   TCP/6000 (TLS 1.2) │◄─── HA Replication          │
│                        └──────────────────────┘                             │
│                                                                             │
│    ┌───────────┐  ┌───────────┐  ┌───────────┐       ┌──────────────────┐   │
│    │  Agent 1  │  │  Agent 2  │  │  Agent N  │       │   thuBeaconGui   │   │
│    │ Workstat. │  │ Workstat. │  │ Workstat. │       │   (Admin PC)     │   │
│    └─────┬─────┘  └──────┬────┘  └───────┬───┘       └──────────┬───────┘   │
│          │               │               │                      │           │
│          └───────────────┴───────────────┴──────────────────────┘           │
│                                    │                                        │
│                          TCP/5000 (TLS 1.2)                                 │
│                          Agent: token auth                                  │
│                          Admin: username/password                           │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

TCP Ports

Port	Protocol	Direction	Purpose
5000	TCP + TLS 1.2	Agent/GUI → Server	Client connections (agents + admin GUI)
6000	TCP + TLS 1.2	Server ↔ Server	HA replication (bidirectional)

Both ports use the same PFX certificate for TLS.

Data Model

Customer (tenant)
  └── Location (site/building)
       └── Device (workstation, identified by hostname)

AgentToken → bound to a Customer
AlertMessage → bound to a Customer, optionally to a Location

Customer = a tenant/organization
Location = a site/building within a customer (messages can target all locations or a specific one)
Device = a workstation running the agent, auto-registered on first connect
Token = an authentication credential bound to a customer; agents use it to prove identity

Alert Messages

Each alert message has the following properties:

Property	Description
Text	The scrolling message text displayed in the banner
Priority	`normal` or `high` — affects visual urgency
DisplayAt	When the message should start appearing (scheduled delivery)
ExpiresAt	When the message stops appearing (auto-hide after this time)
IsClosable	Whether users can dismiss the banner manually
DurationMinutes	How long the banner stays visible per display cycle
RepeatIntervalMinutes	Re-show the banner at this interval (0 = show once)
LocationId	Target a specific location, or empty for all locations

Installation

Server (Automated)

Use the PowerShell install script for a fully automated setup:

# Minimal install — self-signed cert, all defaults
.\Install-thuBeaconServer.ps1

# Custom certificate DNS names
.\Install-thuBeaconServer.ps1 -CertDnsNames "thubeacon-1.thu.ch","thubeacon-2.thu.ch","localhost"

# With existing PFX certificate
.\Install-thuBeaconServer.ps1 -CertificateFile "C:\certs\server.pfx" -CertificatePassword "MyPassword!"

# HA setup (run on each server, adjust -HaPeerHost accordingly)
.\Install-thuBeaconServer.ps1 -HaEnabled true -HaPeerHost "thubeacon-2.thu.ch" -HaSharedSecret "YourSecret!"

The script performs the following steps:

Copies thuBeaconServer.exe + thuBeaconServer.exe.config to the install directory
Creates data and log directories
Generates a self-signed TLS certificate (or copies an existing PFX if provided)
Patches thuBeaconServer.exe.config with all supplied parameters
Registers the Windows service (auto-start, restart-on-failure recovery)
Creates inbound firewall rules (TCP/5000 for clients, TCP/6000 if HA enabled)
Starts the service

Key parameters:

Parameter	Default	Description
`-SourceDir`	Script directory	Folder containing the compiled binaries
`-InstallDir`	`C:\Program Files\thuinformatik GmbH\thuBeacon\Server`	Installation path
`-CertDnsNames`	`thubeacon.thuinformatik.local, localhost`	DNS SANs for the self-signed certificate
`-CertificateFile`	(auto-generated)	Path to an existing PFX file
`-CertificatePassword`	`thuBeacon2026!`	PFX password
`-HaEnabled`	`false`	Enable HA replication
`-HaPeerHost`	(empty)	HA peer server hostname
`-HaSharedSecret`	(empty)	HA HMAC-SHA256 shared secret
`-NoStart`	(off)	Register service but don't start it
`-NoFirewall`	(off)	Skip firewall rule creation

All App.config settings (security, password policy, logging, scheduler, etc.) are also available as parameters. Run Get-Help .\Install-thuBeaconServer.ps1 -Detailed for the full list.

Server (Manual)

Copy thuBeaconServer.exe + thuBeaconServer.exe.config to: C:\Program Files\thuinformatik GmbH\thuBeacon\Server\
Create the TLS certificate (see TLS Certificate below).
Register as a Windows service: cmd sc create thuBeaconServer binPath= "C:\Program Files\thuinformatik GmbH\thuBeacon\Server\thuBeaconServer.exe" start= auto DisplayName= "thuBeacon Server" sc description thuBeaconServer "thuinformatik thuBeacon server - manages agents, messages, and admin connections." sc start thuBeaconServer

Or run interactively for testing: cmd thuBeaconServer.exe --console

Default credentials:
User: admin
Password: admin

⚠️ Change the default password immediately after first login! Connect with thuBeaconGui and change the admin password via the user management interface.

Agent (MSI)

Use the MSI installer package for silent deployment:

Silent install with configuration:

.\Install-thuBeaconAgent.ps1 -ServerHost "thubeacon-1.thu.ch" -ServerPort 5000 -AgentToken "Mq4q2IU3..."

With secondary server (HA failover):

.\Install-thuBeaconAgent.ps1 -ServerHost "thubeacon-1.thu.ch" -SecondaryServerHost "thubeacon-2.thu.ch" -AgentToken "Mq4q2IU3..."

CMD wrapper (for Group Policy / SCCM deployment):

Install-thuBeaconAgent.cmd -ServerHost "thubeacon-1.thu.ch" -AgentToken "token"

Deployment tips:

Use Install-thuBeaconAgent.cmd for GPO/SCCM — it wraps the PS1 with -ExecutionPolicy Bypass
Pre-fill defaults directly in Install-thuBeaconAgent.ps1 for zero-parameter deployment
All parameters can be passed on the command line or pre-filled in the script

MSI manual install + uninstall:

msiexec /i thuBeaconAgent-1.4.2.0-x64.msi /qn /norestart
msiexec /x thuBeaconAgent-1.4.2.0-x64.msi /qn

The agent installs to C:\Program Files\thuinformatik GmbH\thuBeacon\Agent\ and registers an auto-run entry in HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Run.

The install script automatically creates the log directory (C:\ProgramData\thuinformatik GmbH\thuBeacon\Agent\Logs) and grants Modify permissions to Authenticated Users (via well-known SID S-1-5-11, language-independent). This ensures the agent can write logs regardless of which user is logged in.

Agent Runtime Behavior

The agent runs as a background application with a system tray icon:

Icon Color	Meaning
🟢 Green	Connected to server
⚪ Gray	Disconnected (reconnecting)

Right-click the tray icon → shows server address, hostname, and exit option
Double-click the tray icon → shows a status balloon notification
On startup, the agent automatically terminates any other running instances (single-instance enforcement)
The agent can also run as a Windows Service (auto-detected: if started by the SCM, it runs as a service; otherwise, it runs interactively with a tray icon)
Use thuBeaconAgent.exe --console to run with a visible console window for debugging

GUI

Use the PowerShell install script:

# Minimal install — copies files, creates desktop + Start Menu shortcuts
.\Install-thuBeaconGui.ps1

# Files only, no shortcuts
.\Install-thuBeaconGui.ps1 -NoShortcut -NoStartMenu

# All users, custom timeouts
.\Install-thuBeaconGui.ps1 -AllUsers -ConnectTimeoutMs 30000

Key parameters:

Parameter	Default	Description
`-SourceDir`	Script directory	Folder containing the compiled binaries
`-InstallDir`	`C:\Program Files\thuinformatik GmbH\thuBeacon\Gui`	Installation path
`-ConnectTimeoutMs`	`15000`	Connection timeout (ms)
`-CommandTimeoutMs`	`30000`	Command/response timeout (ms)
`-LogFolder`	`%ProgramData%\...\Gui\Logs`	Log directory
`-AllUsers`	(off)	Create shortcuts for all users (requires admin)
`-NoShortcut`	(off)	Skip desktop shortcut
`-NoStartMenu`	(off)	Skip Start Menu entry

Note: Server connection details (host, port, username, password, HA, certificate settings, MaxMessageSizeMB) are no longer configured via the installer or App.config. They are managed in the GUI via File → Connection Details... and stored in %ProgramData%\thuinformatik GmbH\thuBeacon\Gui\connections.json. See Connection Profiles below.

The GUI installs to C:\Program Files\thuinformatik GmbH\thuBeacon\Gui\ and creates shortcuts under thuinformatik GmbH\thuBeacon in the Start Menu.

Connection Profiles

Connection details are managed via File → Connection Details... in the GUI and stored in:

%ProgramData%\thuinformatik GmbH\thuBeacon\Gui\connections.json

Each connection profile contains:

Field	Description
Connection Name	Display name for the profile
Auto-Connect	Connect automatically on GUI startup (only one profile allowed)
HA Configuration	Enable primary/secondary server failover
Server / Primary Server	Server hostname
Port	Server port
Secondary Server	Secondary server hostname (HA only)
Secondary Port	Secondary server port (HA only)
Accept Any Certificate	Accept self-signed TLS certificates
Username	Admin username
Password	Admin password (stored as base64)
Max Message Size (MB)	Protocol message size limit (default: 10)

Auto-Connect: If a profile has Auto-Connect enabled, the GUI will automatically connect to that server on startup. Only one profile can have Auto-Connect enabled at a time.

HA Failover: When HA Configuration is enabled, the GUI will automatically fail over to the secondary server if the primary connection is lost, and fail back when the primary becomes available.

GUI Features

Devices Tab

The Devices tab shows all registered devices with the following columns:

Column	Description
Hostname	Device hostname
User	Currently logged-on Windows username
Customer	Customer the device belongs to
Location	Assigned location (if any)
Last Seen	Last heartbeat timestamp
Server	The server host the device is connected to (as configured in the agent's `ServerHost` setting)
Remote IP	The device's public/NAT IP address as seen by the server (from the TCP connection)
Local IP	The device's internal LAN IP address (reported by the agent)
Agent Version	Running agent software version
Config	Config deployment sync status: ✓ synced, ✗ out of sync, — unknown
Script	Script deployment sync status: ✓ synced, ✗ out of sync, — unknown

Note: Server, Remote IP, Local IP, Agent Version, Config, and Script are only shown for online devices. Online/offline status is indicated by row color (green = online, gray = offline). The "Server" column displays the configured ServerHost from the agent's config (e.g., thubeacon-1.thu.ch), not the server's machine hostname. This is useful in HA setups to see which server each device is connected to.

Device Actions

Select a device and use the action buttons:

Button	Description
Assign	Assign the device to a location (select location in dropdown first)
Unassign	Remove location assignment (device receives all customer messages)
Drop	Disconnect the agent's current TCP session. The agent will reconnect automatically on its next heartbeat cycle. Only works for online devices.
Send Msg	Send a direct banner message to the selected device
Delete	Permanently remove the device record from the server. If the agent is online, it is disconnected first. If the agent is still running, it will re-register on its next connection. Use this to clean up old/decommissioned devices.

Tip: To permanently remove a decommissioned device, first uninstall the agent from the workstation, then delete the device record in the GUI. If you delete without uninstalling, the agent will re-register on its next connection.

Devices Auto-Refresh

The Devices tab includes an auto-refresh feature:

Auto-refresh checkbox — enables/disables automatic refreshing
Interval input — refresh interval in seconds (min: 3, max: 3600, default: 10)

When enabled, the device list refreshes automatically at the specified interval while the Devices tab is active. Auto-refresh pauses when switching to other tabs and disables itself on connection loss.

HA Status Indicator

The GUI displays a colored status indicator next to the HA status text in the connection area:

Indicator	Meaning
🟢 Green	HA enabled, peer connected and syncing
⚪ Gray	HA disabled
🔴 Red/Orange	HA enabled but peer disconnected, or error communicating with server

The indicator updates automatically every 10 seconds.

Token Management

The Tokens tab provides two copy options:

Button	Copies	Use with
Copy Plain	Plaintext token	`TokenIsEncrypted = false` (default agent config)
Copy Enc.	AES-256-CBC encrypted token	`TokenIsEncrypted = true` (enhanced security agent config)

The encrypted value is retrieved directly from the server and matches the server's EncryptionKey.

TLS Certificate

Both server and HA replication use the same PFX certificate.

Generate Self-Signed Certificate (PowerShell)

# Generate cert with SANs for your server hostname(s)
$cert = New-SelfSignedCertificate `
    -DnsName "thubeacon.thuinformatik.local","thubeacon-1.thu.ch","thubeacon-2.thu.ch","localhost" `
    -CertStoreLocation "Cert:\LocalMachine\My" `
    -NotAfter (Get-Date).AddYears(5) `
    -KeyLength 2048 `
    -KeyExportPolicy Exportable

# Export to PFX
$password = ConvertTo-SecureString -String "thuBeacon2026!" -Force -AsPlainText
New-Item -Path "C:\Program Files\thuinformatik GmbH\thuBeacon\Server" -ItemType Directory -Force | Out-Null
Export-PfxCertificate -Cert $cert -FilePath "C:\Program Files\thuinformatik GmbH\thuBeacon\Server\thuBeaconServer.pfx" -Password $password

Hint: Alternatively use the New-TlsCertificate.ps1 script to generate a new TLS certificate.

Server Configuration

In thuBeaconServer.exe.config:

<add key="CertificateFile" value="thuBeaconServer.pfx" />
<add key="CertificatePassword" value="thuBeacon2026!" />

The certificate file path is relative to DataFolder (default: %ProgramData%\thuinformatik GmbH\thuBeacon\Server), or use an absolute path.

Agent Auto-Update

The server can automatically push new agent versions to connected agents.

How It Works

Configure the server with the path to the new agent exe and its version number
After authenticating, the agent sends CHECK_UPDATE with its current assembly version
The server compares versions — if AgentUpdateVersion is newer, it reads the file, computes its SHA256 hash, and sends UPDATE_AVAILABLE to the agent
The agent requests the file — the server streams it in 64 KB base64-encoded chunks
The agent reassembles the file, verifies the SHA256 hash, writes it to a temp directory
A batch script is launched that waits for the agent process to exit, replaces the exe, and restarts it

Server Configuration

In thuBeaconServer.exe.config:

<add key="AgentUpdateFile" value="C:\Deploy\thuBeaconAgent.exe" />
<add key="AgentUpdateVersion" value="1.4.0" />

Key	Description
`AgentUpdateFile`	Full path to the new `thuBeaconAgent.exe` on the server. Supports `%environment%` variables.
`AgentUpdateVersion`	Version string (e.g., `1.4.0`). Must be parseable as `System.Version`.

Note: The server computes the SHA256 hash at runtime — you do not need to configure it. To verify the hash before deployment, use PowerShell or certutil.

Verifying the Agent File Hash

PowerShell:

Get-FileHash -Algorithm SHA256 "C:\Deploy\thuBeaconAgent.exe" | Format-List

Command Prompt (certutil):

certutil -hashfile "C:\Deploy\thuBeaconAgent.exe" SHA256

Agent Configuration

In thuBeaconAgent.exe.config:

<add key="AutoUpdateEnabled" value="true" />

Set to false to prevent the agent from accepting exe updates.

Note: AutoUpdateEnabled only controls exe updates. File deployment (config/script) is controlled separately by FileDeployEnabled. See File Deployment for details.

Update File Location

The agent writes the downloaded update to:

%ProgramData%\thuinformatik GmbH\thuBeacon\Agent\Updates\

The updater batch script is also created in this directory and self-deletes after execution.

Deploying an Update

Place the new thuBeaconAgent.exe on the server
Update AgentUpdateFile and AgentUpdateVersion in thuBeaconServer.exe.config
Restart the server service — the config is read once at startup, so a restart is required: cmd sc stop thuBeaconServer sc start thuBeaconServer
Agents do not need a manual restart — each agent automatically sends a CHECK_UPDATE request after every successful authentication. Connected agents will pick up the update on their next reconnection cycle. New agents connecting for the first time will also receive the update immediately.

Note: If you want agents to update sooner without waiting for a natural reconnect, you can restart the server — this forces all agents to reconnect and trigger their update check.

Security

The file is transferred over the existing TLS 1.2 connection
SHA256 hash is computed by the server and verified by the agent before applying
If the hash doesn't match, the update is rejected and the agent continues running the current version
File-locked scenarios (Terminal Server) are handled gracefully — the update is skipped and retried on the next connection

File Deployment (Config & Script)

The server can automatically deploy updated versions of thuBeaconAgent.exe.config and Configure-thuBeaconAgent.ps1 to connected agents. File deployment is independent of auto-update — you can enable file deployment while keeping exe auto-updates disabled, or vice versa.

How It Works

After authenticating, the agent requests file deployment offers from the server
If AutoUpdateEnabled=true: offers come as part of the CHECK_UPDATE response
If AutoUpdateEnabled=false and FileDeployEnabled=true: agent sends a separate CHECK_FILE_DEPLOY request
Config deployment: The server computes a SHA-256 hash of the template (ignoring customer-specific keys). The agent computes the same hash on its local config. If they differ, the agent downloads the template and merges it — preserving AgentToken, TokenIsEncrypted, and EncryptionKey so connectivity is never lost.
Script deployment: The server sends the file's last-modified UTC timestamp. The agent compares it against its local copy and downloads when the server version is newer.
After each check, the agent reports its sync status (DEPLOY_STATUS) to the server, which is visible in the GUI's Devices tab.

Agent Configuration

In thuBeaconAgent.exe.config:

<add key="FileDeployEnabled" value="true" />

Key	Default	Description
`FileDeployEnabled`	`true`	Accept config and script deployments from the server. Independent of `AutoUpdateEnabled`.

Behavior matrix:

AutoUpdateEnabled	FileDeployEnabled	Exe Update	Config/Script Deploy
true	true	✓	✓
true	false	✓	✗
false	true	✗	✓
false	false	✗	✗

Server Configuration

In thuBeaconServer.exe.config (in the Agent Auto-Update section):

<!-- Config deployment -->
<add key="AgentConfigDeployEnabled" value="true" />
<add key="AgentConfigTemplateFile" value="C:\Deploy\thuBeaconAgent.exe.config" />

<!-- Script deployment -->
<add key="AgentScriptFile" value="C:\Deploy\Configure-thuBeaconAgent.ps1" />

Key	Default	Description
`AgentConfigDeployEnabled`	`false`	Must be `true` to enable config deployment
`AgentConfigTemplateFile`	(empty)	Full path to the config template on the server. Supports `%environment%` variables.
`AgentScriptFile`	(empty)	Full path to the PowerShell script on the server. Supports `%environment%` variables.

Protected Keys

The following config keys are never overwritten during config deployment — they are customer-specific and different on every agent:

Key	Reason
`AgentToken`	Unique authentication token per customer
`TokenIsEncrypted`	Whether the token is AES-encrypted
`EncryptionKey`	AES-256-CBC encryption key

These keys are also excluded from the SHA-256 comparison, so different token values across agents won't cause unnecessary downloads.

Deploying a Config Update

Prepare the config template (a standard thuBeaconAgent.exe.config with your desired settings)
Set AgentConfigDeployEnabled = true and AgentConfigTemplateFile to the template path
Restart the server service
Agents will receive the config on their next connection and apply it — changes take effect on the next agent restart (or the next auto-update cycle, which restarts the agent)

Deploying a Script Update

Place the updated Configure-thuBeaconAgent.ps1 on the server
Set AgentScriptFile to the file path
Restart the server service
Agents compare timestamps and download when the server's copy is newer
The script is written next to the agent exe (C:\Program Files\thuinformatik GmbH\thuBeacon\Agent\)

Notes

File deployment only runs when no exe update is pending (if an exe update is available, the agent downloads and restarts first — file deployment happens on the next connection)
Files are transferred over the existing TLS 1.2 connection using the same 64 KB chunked base64 streaming as exe updates
Config changes require an agent restart to take effect. The agent logs: "config updated successfully. Changes take effect on next restart."
Config and script transfers run concurrently — the agent tracks each file type independently
The agent reports its sync status to the server after each check. The GUI displays this as ✓ (synced) or ✗ (out of sync) in the Devices tab's Config/Script columns

Analytics

The agent periodically collects and submits system analytics to the server. The GUI provides charts, data grids, maintenance suggestions, and connection timelines.

What Is Collected

Category	Data Points
Hardware	Vendor, model, BIOS version, device type (Desktop/Laptop/Server/VM)
CPU	Name, core count, current load %
Memory	Total MB, used MB, memory configuration (e.g., "2x8GB DDR4")
GPU	Graphics adapter name, load % (if available)
Disk	Read/write bytes per second
Network	Sent/received bytes per second, WLAN SSIDs
OS	OS version string
Printers	Installed printers (comma-separated)
Boot	Last boot time
Connection	Connected since timestamp

Note: Serial number and Windows Update status collection were removed in v1.4.1 due to unreliable results across different Windows versions and hardware configurations.

Agent Configuration

<add key="AnalyticsIntervalSeconds" value="300" />

Analytics are submitted every 5 minutes by default. Set to 0 to disable.

Server Configuration

<add key="AnalyticsEnabled" value="true" />
<add key="AnalyticsRetentionDays" value="365" />

Key	Default	Description
`AnalyticsEnabled`	`true`	Enable analytics collection and storage
`AnalyticsRetentionDays`	`365`	Auto-delete analytics data older than N days

Analytics data is stored as daily JSON files in {DataFolder}/analytics/.

GUI — Analytics Tab

The Analytics tab in thuBeaconGui has four sub-tabs:

Sub-Tab	Description
Data	Searchable grid of all analytics records with hardware/OS details. Individual records can be deleted.
Charts	Interactive charts with customer and device filter dropdowns
Maintenance	Suggested maintenance windows based on lowest device activity
Timeline	Per-device connection sessions with duration

Charts

Four chart types are available:

Chart	Description	Filterable by Device?
CPU Load Over Time	Line chart of CPU %	✅ Yes
Memory Usage Over Time	Area chart of memory %	✅ Yes
Connected Devices	Hourly unique device count	❌ No (aggregate)
Devices by Customer	Vertical bar chart of unique devices per customer	❌ No (aggregate)

All charts can be filtered by customer. CPU and Memory charts additionally support per-device filtering. The device dropdown is automatically populated based on the selected customer.

Maintenance Window Suggestions

The server analyzes the last 30 days of analytics data and identifies the top 10 hourly time slots with the lowest average connected device count — ideal for scheduling maintenance.

Zero-activity hour slots (no connected devices) are included and ranked as ideal windows
Day-of-week averaging uses the number of observed calendar days for accurate results
Requires at least 7 days of data (ideally 30) for meaningful suggestions
Results are per-customer or across all customers
If insufficient data is available, an informational message explains what's needed

Connection Timeline

Shows per-device connection sessions with:

Hostname, username, customer
Connection start time
Session duration (e.g., "2d 5h 30m")
Sorted by most recent connections first

Agent and GUI Certificate Validation

By default, both agents and the GUI accept any TLS certificate (AcceptAnyCertificate = true). For production, set this to false and install the server's CA certificate in the Windows trust store on each workstation.

Encryption Key & Token Encryption

The encryption key is used for AES-256-CBC encryption of agent tokens. Tokens are always encrypted at rest on the server. Agents can optionally pre-encrypt tokens before sending them over the wire, adding a second layer of protection on top of TLS.

Key Properties

Property	Value
Algorithm	AES-256-CBC
Padding	PKCS7
IV	16 bytes, randomly generated per encryption, prepended to ciphertext
Key format	Base64-encoded string (padded/truncated to 32 bytes internally)
Must match	Server `EncryptionKey` = Agent `EncryptionKey` (identical on all components)
Default key	`dGh1aW5mb3JtYXRpay10aHViZWFjb24tMjAyNg==`

Generate a New Key (PowerShell)

# Option 1: From a passphrase (deterministic, reproducible)
[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("thuinformatik-thubeacon-2026"))
# Output: dGh1aW5mb3JtYXRpay10aHViZWFjb24tMjAyNg==

# Option 2: Cryptographically random 32-byte key (recommended for production)
$bytes = New-Object byte[] 32
[Security.Cryptography.RNGCryptoServiceProvider]::Create().GetBytes($bytes)
[Convert]::ToBase64String($bytes)
# Output: (random base64 string, e.g. "xY3kL9m2...")

# Verify / decode a passphrase-based key:
[Text.Encoding]::UTF8.GetString([Convert]::FromBase64String("dGh1aW5mb3JtYXRpay10aHViZWFjb24tMjAyNg=="))
# Output: thuinformatik-thubeacon-2026

How Token Encryption Works

There are two modes for agent authentication tokens:

Mode 1: Plaintext Token (default)

The simplest setup. The token is sent in plaintext over the TLS-encrypted connection.

Agent Config:
  AgentToken        = Mq4q2IU3abc123...       (plaintext, as copied from GUI)
  TokenIsEncrypted  = false                     (default)

Flow:

Admin creates token in thuBeaconGui -- server generates a random 32-byte token
Server stores the token AES-encrypted in tokens.json (encrypted at rest)
Admin clicks "Copy" in the GUI -- receives the plaintext token
Admin deploys the plaintext token to agents (via install script or config file)
Agent sends the plaintext token in AUTH_AGENT over TLS
Server decrypts its stored copy and compares

Security: Token is encrypted at rest on the server. In transit, it is protected by TLS 1.2. The plaintext token exists in the agent's config file on disk.

Mode 2: Pre-Encrypted Token (enhanced security)

The agent encrypts the token with AES-256-CBC before sending it. This means the plaintext token never appears in the agent's config file.

Agent Config:
  AgentToken        = <base64 encrypted blob>   (IV + ciphertext)
  TokenIsEncrypted  = true
  EncryptionKey     = dGh1aW5mb3JtYXRpay10aHViZWFjb24tMjAyNg==

Flow:

Admin creates a token in thuBeaconGui — server generates and stores it encrypted
Admin clicks "Copy Enc." in the GUI — the encrypted token is copied to the clipboard (uses the server's encryption key, no manual encryption needed)
Admin deploys the encrypted blob + encryption key to agents
Agent decrypts the token in memory at startup, then sends the plaintext in AUTH_AGENT over TLS
Server decrypts its stored copy and compares

💡 Tip: The "Copy Enc." button in thuBeaconGui retrieves the token in its already-encrypted form directly from the server. This is the recommended way to obtain encrypted tokens — no PowerShell encryption scripts needed. The encryption key used matches the server's EncryptionKey configuration.

Security: The plaintext token never touches the agent's disk. Even if the config file is compromised, the attacker needs both the encrypted blob AND the encryption key to recover the token.

Encrypt a Token with PowerShell (Alternative)

Note: The easiest way to get an encrypted token is to use the "Copy Enc." button in thuBeaconGui. The PowerShell method below is provided as an alternative for scripting or automation scenarios.

Use this to convert a plaintext token into an encrypted blob for agent deployment:

# ── Encrypt a plaintext token ──
$key       = [Convert]::FromBase64String("dGh1aW5mb3JtYXRpay10aHViZWFjb24tMjAyNg==")
$plaintext = "Mq4q2IU3abc123YourPlaintextTokenHere"   # <-- paste your token

# Pad/truncate key to 32 bytes (matches CryptoHelper.PadKey behavior)
$keyPadded = New-Object byte[] 32
[Array]::Copy($key, $keyPadded, [Math]::Min($key.Length, 32))

# Encrypt with AES-256-CBC
$aes         = [Security.Cryptography.Aes]::Create()
$aes.KeySize = 256
$aes.Mode    = [Security.Cryptography.CipherMode]::CBC
$aes.Padding = [Security.Cryptography.PaddingMode]::PKCS7
$aes.Key     = $keyPadded
$aes.GenerateIV()

$encryptor   = $aes.CreateEncryptor()
$plainBytes  = [Text.Encoding]::UTF8.GetBytes($plaintext)
$cipherBytes = $encryptor.TransformFinalBlock($plainBytes, 0, $plainBytes.Length)

# Combine IV (16 bytes) + ciphertext and encode as base64
$blob = New-Object byte[] ($aes.IV.Length + $cipherBytes.Length)
[Array]::Copy($aes.IV, 0, $blob, 0, $aes.IV.Length)
[Array]::Copy($cipherBytes, 0, $blob, $aes.IV.Length, $cipherBytes.Length)
$encrypted = [Convert]::ToBase64String($blob)

Write-Host "Encrypted token (put this in AgentToken):"
Write-Host $encrypted

Then configure the agent:

<add key="AgentToken" value="<paste encrypted output here>" />
<add key="TokenIsEncrypted" value="true" />
<add key="EncryptionKey" value="dGh1aW5mb3JtYXRpay10aHViZWFjb24tMjAyNg==" />

Decrypt a Token with PowerShell (for verification)

# ── Decrypt an encrypted token (for testing/verification) ──
$key       = [Convert]::FromBase64String("dGh1aW5mb3JtYXRpay10aHViZWFjb24tMjAyNg==")
$encrypted = "<paste encrypted base64 blob here>"

$keyPadded = New-Object byte[] 32
[Array]::Copy($key, $keyPadded, [Math]::Min($key.Length, 32))

$allBytes = [Convert]::FromBase64String($encrypted)
$iv = $allBytes[0..15]
$cipherBytes = $allBytes[16..($allBytes.Length - 1)]

$aes         = [Security.Cryptography.Aes]::Create()
$aes.KeySize = 256
$aes.Mode    = [Security.Cryptography.CipherMode]::CBC
$aes.Padding = [Security.Cryptography.PaddingMode]::PKCS7
$aes.Key     = $keyPadded
$aes.IV      = $iv

$decryptor  = $aes.CreateDecryptor()
$plainBytes = $decryptor.TransformFinalBlock($cipherBytes, 0, $cipherBytes.Length)
$plaintext  = [Text.Encoding]::UTF8.GetString($plainBytes)

Write-Host "Decrypted token: $plaintext"

Automated Deployment with Encrypted Tokens

The Install-thuBeaconAgent.ps1 script supports encrypted tokens directly:

# Deploy with pre-encrypted token
.\Install-thuBeaconAgent.ps1 `
    -ServerHost "thubeacon.thu.ch" `
    -AgentToken "<encrypted base64 blob>" `
    -TokenIsEncrypted "true" `
    -EncryptionKey "dGh1aW5mb3JtYXRpay10aHViZWFjb24tMjAyNg==" `
    -AcceptAnyCertificate "true"

Or use Configure-thuBeaconAgent.ps1 post-install:

.\Configure-thuBeaconAgent.ps1 `
    -AgentToken "<encrypted base64 blob>" `
    -TokenIsEncrypted "true" `
    -EncryptionKey "dGh1aW5mb3JtYXRpay10aHViZWFjb24tMjAyNg=="

When to Use Encrypted Tokens

Scenario	Recommended Mode
Internal network, trusted workstations	Plaintext (simpler)
Tokens deployed via GPO/SCCM scripts	Encrypted (token not visible in script logs)
Config files accessible to end users	Encrypted (protects token on disk)
Compliance requirements (PCI, ISO 27001)	Encrypted
Quick testing / lab setup	Plaintext

Key Rotation (Automated)

Since version 1.4.2, key rotation is fully automated via the GUI:

Menu: File → Rotate Tokens...

How It Works

Admin enters a new passphrase in the Rotate Tokens dialog
The passphrase is hashed with SHA-256 to derive a 256-bit AES key (base64)
The server re-encrypts all active tokens with the new key
The old key is preserved as "previous key" for backward compatibility
Connected agents immediately receive their new credentials (ROTATE_CREDENTIALS)
Offline agents receive new credentials on their next connection
Once all agents are rotated, the admin clicks Flush Previous Key to finalize

Rotation Dialog

Section	Description
Current Encryption Key	Shows the active key (base64) — read-only
New Passphrase	Enter ≥8 characters; SHA-256 hashed to derive the new key
Rotate Tokens button	Starts the rotation (requires confirmation)
Rotation Status	Shows rotation ID, start time, progress (X/Y agents)
Pending Devices	Lists devices that haven't received new credentials yet
Refresh button	Refreshes the status from the server
Flush Previous Key	Finalizes rotation — old credentials stop working

What Happens on the Agent

When an agent receives ROTATE_CREDENTIALS:

If TokenIsEncrypted=true: updates both AgentToken (re-encrypted) and EncryptionKey in its local config
If TokenIsEncrypted=false: updates only AgentToken (plaintext)
Updates in-memory values so reconnection works without restart
Sends ROTATE_CREDENTIALS_ACK back to the server

Transition Period (Dual-Key)

During rotation, the server accepts authentication with both the new and old keys. This means:

Already-rotated agents authenticate normally with the new key
Not-yet-rotated agents still authenticate with the old key
No connectivity loss for any agent during the transition

Flushing the Previous Key

⚠️ WARNING: After flushing, only the new key works. Any agent that hasn't received new credentials will permanently lose connectivity and must be manually reconfigured.

The GUI shows a warning with the number of pending devices before flushing. If any devices are pending, you must type "FLUSH" to confirm.

Rotation State Persistence

The rotation state is stored in rotation-state.json in the server's data folder. If the server restarts during a rotation, the state is preserved and agents will continue to receive new credentials on connect.

Best Practices

Wait for all agents to acknowledge before flushing
Monitor the pending list — offline agents will rotate on their next connection
If an agent is permanently offline, remove it from the system or accept it will need manual reconfiguration
The server's EncryptionKey in App.config doesn't need to change — rotation state is managed in the data folder
Rotation can be performed without restarting the server service

Manual Key Rotation (Legacy)

If you need to rotate manually (e.g., migrating from a version without automated rotation):

Generate a new key (see above)
Update EncryptionKey on the server — restart the service
Re-issue all tokens in thuBeaconGui
Deploy the new EncryptionKey + re-encrypted tokens to all agents

Note: The automated rotation method is strongly preferred as it avoids downtime.

Customers, Locations & Tokens

Concepts

Entity	Purpose	Created via
Customer	Top-level tenant. All data is scoped per customer.	thuBeaconGui
Location	Optional sub-grouping (building, floor, site). Messages can target one location or all.	thuBeaconGui
Token	Auth credential for agents. Bound to exactly one customer. Multiple tokens per customer allowed.	thuBeaconGui

Workflow

Create Customer in thuBeaconGui (e.g., "Contoso AG")
Create Locations under that customer (e.g., "Headquarters", "Branch Office")
Create Token for the customer:
Click "Copy" to get the plaintext token (for TokenIsEncrypted = false)
Click "Copy Enc." to get the pre-encrypted token (for TokenIsEncrypted = true)
Deploy agents with that token → agents auto-register as devices under the customer
Assign devices to locations via thuBeaconGui (optional — unassigned devices receive all customer messages)

Cross-Customer Views

The Locations, Devices, Messages, and Tokens tabs all support an (All Customers) option in the customer dropdown. Select it to view data across all customers at once.

The Locations tab shows a Customer column when viewing all customers
Create/Add operations require a specific customer to be selected
Edit, delete, copy, and assign operations work on the selected row regardless of the filter

Message Targeting

Message with LocationId = "" → sent to all devices of that customer
Message with LocationId = "xyz" → sent only to devices assigned to that location

Banner Appearance

The scrolling alert banner is displayed at the top of the screen on the primary monitor. All visual properties are configurable per agent:

Setting	Config Key	Default	Description
Height	`BannerHeight`	28 px	Banner strip height
Default background	`BannerDefaultBackColor`	`#01307a`	Default background color (hex)
Default text color	`BannerDefaultForeColor`	`#ffffff`	Default foreground/text color (hex)
Font size	`BannerFontSize`	15	Font size in points
Scroll speed	`ScrollSpeedPixels`	2	Pixels moved per tick
Scroll interval	`ScrollIntervalMs`	30	Milliseconds between ticks

Per-Message Colors

Alert messages can have individual colors set in thuBeaconGui when creating or editing a message. The color pickers in the Messages tab allow choosing a custom Back Color and Font Color per message, with preset buttons for common colors (dark red, dark green, dark orange, dark blue for backgrounds; white and black for text).

Color priority:

Per-message color — if a message has BackColor / ForeColor set (non-empty), the banner uses those colors
Agent default — if the message has no color set, the agent falls back to BannerDefaultBackColor / BannerDefaultForeColor from its local thuBeaconAgent.exe.config

This allows administrators to use different banner colors for different message types (e.g., red for emergencies, blue for informational) while keeping a consistent default appearance across all agents.

Direct messages sent via the "Send Msg" button on the Devices tab always use the agent's default colors.

Configuration: Non-HA (Single Server)

Server (`thuBeaconServer.exe.config`)

<add key="ListenPort" value="5000" />
<add key="CertificateFile" value="thuBeaconServer.pfx" />
<add key="CertificatePassword" value="thuBeacon2026!" />
<add key="DataFolder" value="%ProgramData%\thuinformatik GmbH\thuBeacon\Server" />
<add key="EncryptionKey" value="dGh1aW5mb3JtYXRpay10aHViZWFjb24tMjAyNg==" />

<!-- HA disabled -->
<add key="HaEnabled" value="false" />

Server — All Settings Reference

Key	Default	Description
`ListenPort`	`5000`	TCP port for agent + admin connections
`CertificateFile`	`thuBeaconServer.pfx`	PFX certificate (relative to DataFolder or absolute)
`CertificatePassword`	`thuBeacon2026!`	PFX password
`DataFolder`	`%ProgramData%\thuinformatik GmbH\thuBeacon\Server`	Data storage root
`EncryptionKey`	(see above)	AES-256-CBC key for token encryption
`LogFolder`	`%ProgramData%\...\Server\Logs`	Log directory
`LogRetentionDays`	`30`	Auto-delete logs older than N days (0 = keep forever)
`SchedulerIntervalMs`	`15000`	Message scheduler check interval (ms)
`HeartbeatTimeoutSeconds`	`120`	Mark agent offline after N seconds without heartbeat
`MaxFailedAuthAttempts`	`5`	Failed logins before IP ban
`AuthLockoutMinutes`	`15`	IP ban duration
`AuthFailureWindowMinutes`	`10`	Time window for counting failures
`MaxConnectionsPerIp`	`200`	Max simultaneous connections per source IP
`MaxConcurrentConnections`	`500`	Global connection limit
`AdminSessionTimeoutMinutes`	`30`	Admin GUI session timeout (0 = no timeout)
`AgentUpdateFile`	(empty)	Path to new agent exe for auto-update
`AgentUpdateVersion`	(empty)	Version string of the update file
`AgentConfigDeployEnabled`	`false`	Enable config template deployment to agents
`AgentConfigTemplateFile`	(empty)	Path to the agent config template file
`AgentScriptFile`	(empty)	Path to Configure-thuBeaconAgent.ps1 for deployment
`AnalyticsEnabled`	`true`	Enable analytics collection
`AnalyticsRetentionDays`	`365`	Analytics data retention (days)
`MaxMessageSizeMB`	`10`	Maximum protocol message size in MB (affects admin commands and HA sync)
`HaReplicateAnalytics`	`true`	Replicate analytics data to HA peer (true/false)
`PasswordMinLength`	`8`	Minimum admin password length
`PasswordRequireUppercase`	`true`	Require uppercase letter
`PasswordRequireLowercase`	`true`	Require lowercase letter
`PasswordRequireDigit`	`true`	Require digit
`PasswordRequireSpecialChar`	`false`	Require special character

Agent (`thuBeaconAgent.exe.config`)

<add key="ServerHost" value="thubeacon.thu.ch" />
<add key="ServerPort" value="5000" />
<add key="SecondaryServerHost" value="" />
<add key="AgentToken" value="your-token-here" />
<add key="EncryptionKey" value="dGh1aW5mb3JtYXRpay10aHViZWFjb24tMjAyNg==" />
<add key="AutoUpdateEnabled" value="true" />
<add key="FileDeployEnabled" value="true" />
<add key="AnalyticsIntervalSeconds" value="300" />

GUI (`thuBeaconGui.exe.config`)

<!-- Connection profiles are stored in connections.json
     (File > Connection Details... in the GUI) -->
<add key="LogFolder" value="%ProgramData%\thuinformatik GmbH\thuBeacon\Gui\Logs" />
<add key="ConnectTimeoutMs" value="15000" />
<add key="CommandTimeoutMs" value="30000" />

Note: Server connection settings (host, port, username, password, HA, certificate, MaxMessageSizeMB) are now stored per-profile in connections.json. See Connection Profiles.

Firewall Rules

Allow TCP/5000 INBOUND on server from agent/admin subnets

Configuration: HA (Two Servers)

Server 1 — `thubeacon-1.thu.ch`

<add key="ListenPort" value="5000" />
<add key="CertificateFile" value="thuBeaconServer.pfx" />
<add key="CertificatePassword" value="thuBeacon2026!" />
<add key="DataFolder" value="%ProgramData%\thuinformatik GmbH\thuBeacon\Server" />
<add key="EncryptionKey" value="dGh1aW5mb3JtYXRpay10aHViZWFjb24tMjAyNg==" />

<!-- HA -->
<add key="HaEnabled" value="true" />
<add key="HaPeerHost" value="thubeacon-2.thu.ch" />
<add key="HaPeerPort" value="6000" />
<add key="HaListenPort" value="6000" />
<add key="HaSharedSecret" value="YourStrongSharedSecret!" />
<add key="HaSyncIntervalMs" value="30000" />
<add key="HaReplicateAnalytics" value="true" />
<add key="MaxMessageSizeMB" value="10" />

Server 2 — `thubeacon-2.thu.ch`

<add key="ListenPort" value="5000" />
<add key="CertificateFile" value="thuBeaconServer.pfx" />
<add key="CertificatePassword" value="thuBeacon2026!" />
<add key="DataFolder" value="%ProgramData%\thuinformatik GmbH\thuBeacon\Server" />
<add key="EncryptionKey" value="dGh1aW5mb3JtYXRpay10aHViZWFjb24tMjAyNg==" />

<!-- HA -->
<add key="HaEnabled" value="true" />
<add key="HaPeerHost" value="thubeacon-1.thu.ch" />
<add key="HaPeerPort" value="6000" />
<add key="HaListenPort" value="6000" />
<add key="HaSharedSecret" value="YourStrongSharedSecret!" />
<add key="HaSyncIntervalMs" value="30000" />
<add key="HaReplicateAnalytics" value="true" />
<add key="MaxMessageSizeMB" value="10" />

HA Replication Details

Protocol: TLS 1.2 over TCP/6000
Authentication: Mutual HMAC-SHA256 challenge-response using HaSharedSecret
Sync: Bidirectional, version-vector based (file-level granularity)
Interval: Every 30 seconds (configurable via HaSyncIntervalMs)
Replicated data: customers, locations, devices, messages, tokens, admins (JSON files)
Analytics replication: Enabled by default (HaReplicateAnalytics = true); can be disabled independently of local analytics collection
Conflict resolution: Higher version number wins

GUI Configuration (HA)

The admin GUI supports automatic failover to a secondary server. HA settings are configured per connection profile via File → Connection Details...:

Open Connection Details and select (or create) a profile
Check HA Configuration?
Enter Primary Server + Port and Secondary Server + Port
Click OK or Apply

Behavior:

On connection loss, the GUI automatically attempts to connect to the secondary server using the same credentials
If already on secondary and connection is lost, it tries the primary first
The status bar shows which server is active (orange text = secondary)
HA status indicator in the status bar shows Primary/Secondary/Standalone
If both servers are unreachable, the user is notified and returned to the login state

Agent Configuration (HA)

Agents support automatic failover between primary and secondary server:

<add key="ServerHost" value="thubeacon-1.thu.ch" />
<add key="ServerPort" value="5000" />
<add key="SecondaryServerHost" value="thubeacon-2.thu.ch" />
<add key="SecondaryServerPort" value="5000" />

On connection failure, the agent alternates between primary and secondary with a configurable reconnect delay (default: 30s ± 10s jitter).

Note: Authentication failures do not trigger server failover — the agent stays on the same server and retries after a delay. This prevents flip-flopping when the issue is a misconfigured token rather than a connectivity problem.

Firewall Rules (HA)

Allow TCP/5000 INBOUND on both servers from agent/admin subnets
Allow TCP/6000 INBOUND on both servers from the peer server IP only

Security Summary

Feature	Details
Transport	TLS 1.2 (all connections)
Agent auth	Token-based (plaintext or AES-encrypted)
Admin auth	Username + salted password hash
HA auth	HMAC-SHA256 challenge-response
Brute force	5 failures in 10 min → 15 min IP ban
Connection limit	Max 200 per IP, 500 global
Protocol limit	10 MB max message size (configurable via `MaxMessageSizeMB`)
Socket timeouts	90s receive, 30s send
Password policy	Min 8 chars, upper + lower + digit required (special char optional)
Default credentials	`admin` / `admin` — change immediately after first login!

Data Flow

[Admin creates message in thuBeaconGui]
     │
     ▼
GUI ──TCP/5000──► Server stores message in data folder (JSON)
     │                     │
     │                     ├──► HA replication to peer (TCP/6000, next sync cycle)
     │                     │
     │                     ▼
     │              MessageScheduler checks every 15s:
     │                "Is it time to display this message?"
     │                (displayAt <= now < expiresAt)
     │                     │
     │                     ▼  (yes → push to matching agents)
     │              SHOW_MESSAGE → all connected agents for that customer/location
     │
     ▼
Agent receives SHOW_MESSAGE → displays scrolling banner on desktop
  │
  ├── If message has repeatIntervalMinutes > 0:
  │     Banner auto-hides after durationMinutes, then re-appears
  │
  ├── If isClosable = true and user clicks close:
  │     Agent sends MESSAGE_DISMISSED → server logs dismissal
  │
  └── When expiresAt is reached:
        Server sends HIDE_MESSAGE → agent removes banner

Log Rotation

All components automatically purge old log files on startup.

Component	Log pattern	Default retention	Config key	Default log folder
thuBeaconServer	`server-.log`, `audit-.log`	30 days	`LogRetentionDays`	`%ProgramData%\...\Server\Logs`
thuBeaconAgent	`agent_*.log`	30 days	`LogRetentionDays`	`%ProgramData%\...\Agent\Logs`
thuBeaconGui	(application logs)	—	—	`%ProgramData%\...\Gui\Logs`

Files older than LogRetentionDays (by last write time) are deleted at startup
Set LogRetentionDays to 0 to disable rotation (keep logs forever)
Cleanup is best-effort — locked or inaccessible files are silently skipped

File Locations

Component	Path
Server binary	`C:\Program Files\thuinformatik GmbH\thuBeacon\Server\`
Server data	`%ProgramData%\thuinformatik GmbH\thuBeacon\Server\`
Server logs	`%ProgramData%\thuinformatik GmbH\thuBeacon\Server\Logs\`
Server certificate	`%ProgramData%\thuinformatik GmbH\thuBeacon\Server\thuBeaconServer.pfx`
Agent binary	`C:\Program Files\thuinformatik GmbH\thuBeacon\Agent\`
Agent logs	`%ProgramData%\thuinformatik GmbH\thuBeacon\Agent\Logs\`
Agent updates	`%ProgramData%\thuinformatik GmbH\thuBeacon\Agent\Updates\`
Analytics data	`%ProgramData%\thuinformatik GmbH\thuBeacon\Server\analytics\`
Agent auto-run	`HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Run\thuBeaconAgent`
GUI binary	`C:\Program Files\thuinformatik GmbH\thuBeacon\Gui\`
GUI logs	`%ProgramData%\thuinformatik GmbH\thuBeacon\Gui\Logs\`

Troubleshooting

Symptom	Cause	Fix
Agent tray icon stays gray	Cannot reach server	Check firewall, verify `ServerHost`/`ServerPort`, check server is running
Auto-update not working	`AgentUpdateFile` or `AgentUpdateVersion` empty	Configure both settings in `thuBeaconServer.exe.config`
File deploy not working	`FileDeployEnabled=false` on agent or `AgentConfigDeployEnabled=false` on server	Check both settings; also verify `AgentConfigTemplateFile`/`AgentScriptFile` paths exist
Config re-deploys every restart	Server template hash doesn't match local file	Ensure agent is v1.4.1+; older versions had a bug where XML reformatting broke hash comparison
Auto-update hash mismatch	File changed after hash was sent	Re-deploy a stable copy of the agent exe; avoid overwriting while agents are updating
Analytics tab empty	Agents haven't reported yet	Wait for at least one analytics interval (default 5 min); check `AnalyticsEnabled=true` on server
Maintenance tab empty	Not enough data	Need at least 7 days of analytics data from multiple devices
Agent log "access denied"	Log directory not writable	Re-run `Install-thuBeaconAgent.ps1` (sets ACL), or manually grant Modify to Authenticated Users on `%ProgramData%\...\Agent\Logs`
"Auth rejected" in agent log	Wrong token or token expired	Verify `AgentToken` matches a valid token in thuBeaconGui
Agent keeps reconnecting	Server heartbeat timeout	Check network stability; increase `HeartbeatIntervalSeconds` if needed
GUI login fails	Wrong credentials or IP banned	Check username/password; wait 15 min if IP is locked out
No banner appears	Message not yet active or already expired	Verify `DisplayAt` and `ExpiresAt` in thuBeaconGui
Banner on wrong monitor	Banner always uses primary monitor	By design — the banner displays on the primary display
HA not syncing	Firewall blocking TCP/6000	Allow TCP/6000 between the two server IPs
"Certificate error"	`AcceptAnyCertificate = false` + untrusted cert	Install the CA cert in the Windows trust store, or set `AcceptAnyCertificate = true` for testing

Quick Start

Install server on a Windows Server machine (see Server installation)
Start the service (sc start thuBeaconServer or --console for testing)
Connect thuBeaconGui to the server (localhost:5000, user admin, password admin)
Change the admin password immediately
Create a customer → create location(s) → create a token → click "Copy" (plaintext) or "Copy Enc." (encrypted)
Deploy agents using the MSI + install script with the token
Send a test message via thuBeaconGui — verify the banner appears on agent workstations

For HA: repeat server setup on second host, enable HA on both, configure agents with both server addresses.

Uninstallation

Server

sc stop thuBeaconServer
sc delete thuBeaconServer

Then delete the install directory and optionally the data/log folders.

Agent

msiexec /x thuBeaconAgent-1.4.2.0-x64.msi /qn

Or via Windows Settings → Apps → thuBeacon Agent → Uninstall.

GUI

Delete the install directory (C:\Program Files\thuinformatik GmbH\thuBeacon\Gui\) and remove any desktop/Start Menu shortcuts.

Source: README.md, updated 2026-05-03

thuBeacon Files

thuBeacon is a client-server system for pushing scrolling alert banner

Get an email when there's a new version of thuBeacon

thuBeacon — Desktop Alert Notification System

Overview

How It Works

Architecture

TCP Ports

Data Model

Alert Messages

Installation

Server (Automated)

Server (Manual)

Agent (MSI)

Agent Runtime Behavior

GUI

Connection Profiles

GUI Features

TLS Certificate

Generate Self-Signed Certificate (PowerShell)

Server Configuration

Agent Auto-Update

How It Works

Server Configuration

Verifying the Agent File Hash

Agent Configuration

Update File Location

Deploying an Update

Security

File Deployment (Config & Script)

How It Works

Agent Configuration

Server Configuration

Protected Keys

Deploying a Config Update

Deploying a Script Update

Notes

Analytics

What Is Collected

Agent Configuration

Server Configuration

GUI — Analytics Tab

Charts

Maintenance Window Suggestions

Connection Timeline

Agent and GUI Certificate Validation

Encryption Key & Token Encryption

Key Properties

Generate a New Key (PowerShell)

How Token Encryption Works

Mode 1: Plaintext Token (default)

Mode 2: Pre-Encrypted Token (enhanced security)

Encrypt a Token with PowerShell (Alternative)

Decrypt a Token with PowerShell (for verification)

Automated Deployment with Encrypted Tokens

When to Use Encrypted Tokens

Key Rotation (Automated)

How It Works

Rotation Dialog

What Happens on the Agent

Transition Period (Dual-Key)

Flushing the Previous Key

Rotation State Persistence

Best Practices

Manual Key Rotation (Legacy)

Customers, Locations & Tokens

Concepts

Workflow

Cross-Customer Views

Message Targeting

Banner Appearance

Per-Message Colors

Configuration: Non-HA (Single Server)

Server (thuBeaconServer.exe.config)

Server — All Settings Reference

Agent (thuBeaconAgent.exe.config)

GUI (thuBeaconGui.exe.config)

Firewall Rules

Configuration: HA (Two Servers)

Server 1 — thubeacon-1.thu.ch

Server (`thuBeaconServer.exe.config`)

Agent (`thuBeaconAgent.exe.config`)

GUI (`thuBeaconGui.exe.config`)

Server 1 — `thubeacon-1.thu.ch`

Server 2 — `thubeacon-2.thu.ch`