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.5.0-x64-dist.zip	2026-05-19	1.2 MB	0
README.md	2026-05-19	97.3 kB	0
Totals: 2 Items		1.2 MB	0

thuBeacon — Desktop Alert Notification System

thuinformatik GmbH | Version 1.4.5 | .NET Framework 4.7.2

Web: https://www.thu.ch
E-Mail: notify@thu.ch
Project: https://sourceforge.net/projects/thubeacon/

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

Compatibility Matrix

Server	GUI	Agent	Supported
1.4.5	1.4.5	1.4.2	✅ Yes
1.4.5	1.4.4	1.4.2	⚠️ GUI lacks delivery archive/flush, SMTP, and update management features
1.4.4	1.4.5	1.4.2	❌ No — GUI sends commands (ARCHIVE_DELIVERY, UPLOAD_*_UPDATE, etc.) that 1.4.4 server does not understand
1.4.4	1.4.4	1.4.2	✅ Yes
1.4.3	1.4.3	1.4.2	✅ Yes
1.4.2	1.4.2	1.4.2	✅ Yes

Note: The agent protocol is unchanged in 1.4.5 — agents do not need to be updated. Always update the server before updating the GUI.

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
The server can distribute GUI updates — admins are prompted to update when connecting to a server with a newer version
Server updates can be uploaded and applied remotely via the GUI (GlobalAdmin only)
Backup & Restore provides full server backup (manual and scheduled) with SHA256 verification, CIFS/SMB support, and cross-compatible HA restore
SMTP email notifications alert administrators when message delivery thresholds are reached

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

SMTP Email Notifications

Since version 1.4.5, the server supports SMTP email notifications for message delivery alerts. When configured, administrators can enable per-message notifications that send an email when a delivery threshold (percentage of target devices) is reached.

Server Configuration (thuBeaconServer.exe.config):

<add key="SmtpServer" value="smtp.company.com" />
<add key="SmtpPort" value="587" />
<add key="SmtpUseTls" value="true" />
<add key="SmtpUsername" value="alerts@company.com" />
<add key="SmtpPassword" value="YourPassword" />
<add key="SmtpSenderAddress" value="alerts@company.com" />

Key	Default	Description
`SmtpServer`	(empty)	SMTP server hostname
`SmtpPort`	`587`	SMTP server port
`SmtpUseTls`	`true`	Use TLS for SMTP connection
`SmtpUsername`	(empty)	SMTP authentication username
`SmtpPassword`	(empty)	SMTP authentication password (AES-256 encrypted at rest)
`SmtpSenderAddress`	(empty)	Sender email address for notifications
`DeliveryRetentionDays`	`90`	Days to retain delivery records before automatic purge

Security note: CryptoHelper provides EncryptCredential() and DecryptCredential() methods used by both Server and GUI for AES-256 encryption of SMTP passwords, connection passwords, and CIFS passwords. DecryptCredential() includes graceful fallback — if AES decryption fails (e.g., legacy plaintext value), the original value is returned unchanged, enabling smooth migration from unencrypted credentials.

GUI — Server Settings:

The SMTP tab in Settings → Server Settings allows Global Admins to configure SMTP remotely. A "Send Test Email" button verifies the configuration by sending a test message to the specified address. The SMTP password is stored encrypted at rest using AES-256-CBC.

Update Wizard (accessed via "Update thuBeacon..." button in Settings → Server Settings) consolidates server, GUI, and agent update management into a single 3-column layout (Server | GUI | Agent). Each column shows:

Installed version — the version currently running (server: connected server version, GUI: local exe version, agent: lowest version among online agents)
Staged version — the update file uploaded to the server (GUI and Agent columns; server updates apply immediately)
Online version — the latest version published on the thuinformatik update server (green/bold when newer than installed)

Each column provides file picker, upload, and delete actions. File pre-checks validate the filename, display FileVersionInfo (version + copyright), and use green/red coloring to indicate validity. Same-version uploads show a warning (downgrades are allowed). All uploads include SHA256 hash verification with automatic retry on mismatch.

The wizard uses dedicated progress dialogs per update type:

GuiAgentUpdateProgressForm — 2-step progress dialog for GUI and Agent uploads (865px width; with HA support: uploads to both servers)
ServerUpdateProgressForm — 5-step progress dialog for Server updates (upload → stop → replace → restart → reconnect; HA: secondary first, then primary; 865px width). Step labels use fixed width with AutoEllipsis and tooltip on hover. 10-second initial wait before first reconnection attempt; 30 attempts × 2-second intervals with countdown timer display; each attempt shows actual error message on failure.

In HA configurations, update uploads are sent to both servers independently (no HA replication needed for update files). The optional Configure-thuBeaconAgent.ps1 script can be uploaded alongside the agent exe and config template. All files are stored in the server's updates\{agent|gui|server}\ directories. Only Global Admins can open Server Settings.

Backup & Restore (accessed via Settings → Backup & Restore, GlobalAdmin only) provides full server backup and restore functionality:

Manual Tab:
Backup directory — select the local directory for storing backup files
Include analytics — optionally include analytics data in the backup (can be large)
Full HA Backup — checkbox to include ALL files from both servers (visible only in HA mode). Uses HA_FORWARD pattern on main client port to collect full file manifest from peer. HA staging directory (backups\ha-staging\) used for temporary storage during collection.
Create Backup — creates a ZIP archive containing all server data: JSON data files (customers, locations, devices, tokens, messages, admins, deliveries, rotation state), TLS certificates, server configuration (thuBeaconServer.exe.config), update files, and optionally analytics
Restore from ZIP — upload a previously created backup file and restore the server to that state
BackupProgressForm — 4-step progress with "Open Folder" button on completion
RestoreProgressForm — 4-step progress; HA dual-section layout (primary section on top, secondary on bottom)
Scheduled Tab:
Destination — local disk or CIFS/SMB network share (mutually exclusive — filling one disables the other)
CIFS configuration — server path (\\server\share), username, password with connectivity test before saving
Interval — configurable backup interval: 1 hour, 2 hours, 4 hours, 8 hours, 12 hours, 1 day, 1 week
Backup time — time-of-day trigger for scheduled backups
Retention — configurable backup retention period (1–52 weeks, default: 12). Backups older than the retention period are automatically deleted daily at midnight. A confirmation dialog is shown when reducing retention.
Full HA Backup — chkScheduleHaFullBackup checkbox (visible only in HA mode) enables scheduled full HA backups
Backup log — view backup history with retention management
Backup Contents:
All JSON data files in the server's data folder
TLS certificates (PFX files)
Server configuration (thuBeaconServer.exe.config)
Update files (updates\agent\, updates\gui\, updates\server\)
Analytics data (optional, controlled by the "Include analytics" checkbox)
index.dat manifest — SHA256 hash of every file in the backup, verified on restore
Security:
Server-side locking prevents concurrent backup/restore operations
SHA256 hash verification via index.dat manifest ensures backup integrity on restore
CIFS/SMB passwords for scheduled backups are encrypted at rest using AES-256 (CryptoHelper.EncryptCredential() in backup-schedule.json). GET_BACKUP_SCHEDULE returns a "********" placeholder — the encrypted or plaintext password is never exposed. TEST_BACKUP_DESTINATION uses the stored encrypted password when the placeholder is provided.
Only GlobalAdmin users can access backup and restore functionality
Chunked Transfer: DOWNLOAD_BACKUP and UPLOAD_RESTORE use chunked transfer protocol to handle backups larger than MaxMessageSizeMB. Dynamic chunk size is 60% of MaxMessageSizeMB (minimum 64 KB, maximum 4 MB). The GUI's BackupProgressForm fetches metadata first, then downloads in chunks and reassembles; RestoreProgressForm sends the file in chunks with progress (chunk X/Y).
HA Backup & Restore: In HA configurations, backup and restore supports both servers:
Full HA Backup: "Full HA Backup (include secondary server)" checkbox on the Manual tab (visible only in HA mode). Full HA backup includes ALL files from BOTH servers (not just cert+config from secondary). The primary collects the secondary's full file manifest via GET_BACKUP_FILES (returns zipEntry, category, absolutePath, size, sha256) and downloads individual files via GET_BACKUP_FILE_DATA (chunked transfer for files larger than MaxLineLength). Uses HA_FORWARD pattern on main client port (not HA port — single-session limitation). HA staging directory (backups\ha-staging\) is used for temporary storage during collection. The resulting ZIP contains primary/ and secondary/ folders. The index.dat manifest includes a #HaEnabled=true header.
HA Restore: When restoring an HA backup in HA mode, the GUI orchestrates the restore across both servers: secondary first, then primary. Each node goes through upload → apply → restart → reconnect. The RestoreProgressForm displays a dual-section progress view (similar to the server update HA pattern). APPLY_RESTORE accepts restoreNode ("primary" or "secondary") and restartAfterRestore parameters.
HA Backup Detection: The restore file picker reads index.dat from the ZIP to detect HA backups and displays an "HA Backup" indicator. If an HA backup is restored without HA mode, only the primary portion is applied (with a warning).
Scheduled HA Backup: The "Full HA Backup" option is also available on the Scheduled tab (chkScheduleHaFullBackup checkbox, visible only in HA mode), enabling scheduled full HA backups.

Cross-Compatible Restore: The restore system supports all 4 backup/target combinations:

Backup Type	Target Mode	Behavior
Single	Single	Entries restored directly
HA	Single	Uses `primary\` entries only
HA	HA	Each server gets entries from its own folder (primary gets `primary\`, secondary gets `secondary\`)
Single	HA	Data to both servers; cert/config only to primary (secondary keeps its own)

Server Path: Backups are stored in %ProgramData%\thuinformatik GmbH\thuBeacon\Server\backups\
HA Staging: Temporary files during HA backup collection are stored in backups\ha-staging\
Schedule Persistence: Scheduled backup configuration is stored in backup-schedule.json

GUI Auto-Update on Connect: When connecting to a server that has a newer GUI version staged, users are prompted to download and apply the update. The self-update replaces the running exe and restarts the application. This check uses the CHECK_GUI_UPDATE command (available to all admin roles).

Note: The previous "File > Check For Updates" menu item and CheckForUpdatesForm have been removed. Update checking is now handled automatically via the per-connection profile CheckForUpdates setting and the UpdateNotificationForm. Version comparison logic has been centralized in VersionHelper.vb (shared utility class with IsNewer() and NormalizeVersion() methods).

GUI — Messages Tab:

Each message can have email notification enabled via the "Enable notification" checkbox. When enabled, specify:

Email address — recipient for the delivery notification
Threshold percent — percentage of target devices that must receive the message before the notification is sent

Message Delivery Tracking

Since version 1.4.4, the server records every message delivery event — whenever a SHOW_MESSAGE is sent to an agent (scheduled delivery, on-connect push, or direct send-to-device). The delivery log tracks:

Field	Description
Hostname	The device hostname that received the message
Username	The logged-on Windows username at the time of delivery
Device ID	The unique device identifier
Message Text	The full message text that was displayed
Delivered At	UTC timestamp of when the message was sent to the agent

GUI: The Messages tab has a "Deliveries" button (before Add/Edit/Delete). Click it to open the Message Deliveries window:

No message selected: Shows all delivery records across all messages
Message selected: Shows only deliveries for that specific message

The deliveries window includes a Refresh button to reload data from the server.

Retention: Delivery records are automatically purged by the server after the configured retention period (once per day). The retention period is configurable via DeliveryRetentionDays (default: 90). Delivery data is stored in deliveries.json in the server's data folder and is replicated via HA sync.

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
Clone	Duplicate an existing connection profile (creates a copy with "(Copy)" suffix)
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 (AES-256 encrypted at rest)
Max Message Size (MB)	Protocol message size limit (default: 10)
Check for updates	Check for component updates after connecting (default: off)

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.

HA Reconnect Prompt: When HA settings are changed (enabled/disabled) in Connection Details and saved, the GUI prompts: "HA configuration has changed. Reconnect now?" Choosing Yes triggers an automatic disconnect + reconnect to apply the new settings immediately.

GUI Features

Menu Structure

The GUI menu bar contains the following menus:

Menu	Items	Visibility
File	Connection Details, Change My Password, About, Exit	All logged-in users
Settings	Analytics Storage, Backup & Restore, Rotate Tokens, Server Settings	Global Admin only

Note: The Settings menu is only visible when connected as a Global Admin.

About Box (File → About) shows:

E-mail: notify@thu.ch
Developer: https://www.thu.ch
Project: https://sourceforge.net/projects/thubeacon Analytics Storage, Rotate Tokens, and Server Settings were moved from the File menu to the Settings menu in version 1.4.3.

Change My Password (File → Change My Password) allows any logged-in user to change their own password. The dialog uses a modern styled layout with current password, new password, and confirmation fields. The new password is validated against the server's password policy before submission.

Auto-Update Check on Connect: Each connection profile has a "Check for updates on server connect" checkbox (in File → Connection Details...). When enabled, the GUI automatically checks for component updates after connecting to the server:

Non-admin users: Checks if a newer GUI version is available online and whether the server has staged a GUI update ready to apply
Global Admin: Checks Server, GUI, and Agent versions against the online update CSV
Agent version: Determined by the lowest version among all online connected agents
The update notification shows a 4-column layout: Component | Installed | Staged | Online
Buttons: Apply GUI Update (if server has staged update), Open Update Settings (opens Update Wizard), Download (opens SourceForge page)
The check runs on a background thread to avoid UI freezing
The update CSV is fetched from https://www.thuinformatik.ch/_updaters/thubeacon/current_version.csv (format: Date_ddmmyyyy;Latest_download;Latest_server;Latest_gui;Latest_agent;Download)

The setting is stored per connection profile in connections.json (not in thuBeaconGui.exe.config).

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:\ProgramData\thuinformatik GmbH\thuBeacon\Server\updates\agent\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:\ProgramData\thuinformatik GmbH\thuBeacon\Server\updates\agent\thuBeaconAgent.exe" | Format-List

Command Prompt (certutil):

certutil -hashfile "C:\ProgramData\thuinformatik GmbH\thuBeacon\Server\updates\agent\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 (or upload it via the Agent Update tab in Server Settings — no manual file placement needed)
Update AgentUpdateFile and AgentUpdateVersion in thuBeaconServer.exe.config (done automatically when using the GUI upload)
Reload the server configuration — use RELOAD_CONFIG to hot-reload without restarting:
Via the GUI: Settings → Server Settings → Save (triggers RELOAD_CONFIG automatically)
Or restart the Windows service if preferred: 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:\ProgramData\thuinformatik GmbH\thuBeacon\Server\updates\agent\thuBeaconAgent.exe.config" />

<!-- Script deployment -->
<add key="AgentScriptFile" value="C:\ProgramData\thuinformatik GmbH\thuBeacon\Server\updates\agent\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
Reload the server configuration (via RELOAD_CONFIG or restart the 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
Reload the server configuration (via RELOAD_CONFIG or restart the 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 five 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 (computed client-side from cached data)
Work Hours	Per-user hourly activity patterns with interactive chart, average start/end times, grouped by Customer/Username/Hostname
Timeline	Per-device connection sessions with Connected/Disconnected timestamps, "Alive" indicator (green) for active sessions, and calculated duration

All five sub-tabs compute client-side using cached analytics records — no extra server round-trips after the initial Load. Switching between sub-tabs or changing the customer filter is instant.

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.

Loading Progress

When loading analytics data, the GUI displays a progress overlay:

Estimating — the GUI queries the server for the number of files and total MB in the selected date range (fast, no data transfer)
Transferring — data is fetched day-by-day in the background; a progress bar shows actual MB transferred vs total (e.g. "3.2 / 13.2 MB"). The GUI remains fully responsive during this phase.
Preparing — after transfer, the records are loaded into the ListView and chart filters are populated

Note: The day-by-day approach avoids transferring all data in a single large response, reducing the chance of hitting the MaxMessageSizeMB limit. If a single day’s data exceeds the limit, the MaxMessageSize dialog is shown as usual. CPU and Memory charts additionally support per-device filtering. The device dropdown is automatically populated based on the selected customer.

Work Hours

The Work Hours sub-tab shows per-user hourly activity patterns:

Interactive chart displaying when users are typically active throughout the day
Average start and end times calculated per user
Grouping by Customer, Username, or Hostname
Computed client-side from cached analytics records

Maintenance Window Suggestions

The GUI analyzes the cached analytics data and identifies the top 10 hourly time slots with the lowest average connected device count — ideal for scheduling maintenance. Maintenance windows are computed client-side from cached data (no server round-trip needed).

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
Connected and Disconnected timestamps
Green "Alive" indicator for currently active sessions
Session duration calculation (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: Settings → 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

Note (v1.4.4): The "Active" column in the Messages ListView now reflects the effective active status — a message shows "No" when its display window has expired (DisplayAt + DurationMinutes), even if the IsActive flag is still true.

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.

Message Deliveries

The Messages tab includes a "Deliveries" button that opens a window showing which users and devices received each message. If a message is selected in the list, only deliveries for that message are shown; otherwise, all delivery records are displayed. The window shows Delivered At (local time), Hostname, Username, Message Text, and Device ID columns.

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
`MaxBannedIpsBeforeUserLockout`	`5`	Distinct banned IPs per user before auto-locking the account
`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
`GuiUpdateFile`	(empty)	Path to GUI exe for auto-update distribution
`GuiUpdateVersion`	(empty)	Version string of the GUI update file
`AnalyticsEnabled`	`true`	Enable analytics collection
`AnalyticsRetentionDays`	`365`	Analytics data retention (days)
`AnalyticsRetentionEnabled`	`false`	Enable daily midnight cleanup of old analytics files
`AnalyticsDefaultDateRangeDays`	`30`	Default date range for GUI analytics queries
`AnalyticsFolder`	(empty)	Custom analytics folder (empty = `{DataFolder}\analytics`)
`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
`SmtpServer`	(empty)	SMTP server hostname for email notifications
`SmtpPort`	`587`	SMTP server port
`SmtpUseTls`	`true`	Use TLS for SMTP connection
`SmtpUsername`	(empty)	SMTP authentication username
`SmtpPassword`	(empty)	SMTP authentication password (AES-256 encrypted at rest)
`SmtpSenderAddress`	(empty)	Sender email address for notifications
`DeliveryRetentionDays`	`90`	Days to retain delivery records before automatic purge

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" />

Note: Both ServerPort (default: 5000) and secondary server port are configurable. The server's ListenPort setting in thuBeaconServer.exe.config controls which port the server listens on. The HA replication ports (HaListenPort and HaPeerPort, default: 6000) are also configurable.

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" />

Key	Default	Description
`LogFolder`	`%ProgramData%\...\Gui\Logs`	Log directory
`ConnectTimeoutMs`	`15000`	Connection timeout (ms)
`CommandTimeoutMs`	`30000`	Command timeout (ms)
`ClientSettingsProvider.ServiceUri`	(empty)	Service URI (documented with XML comment by EnsureConfigKeys)

Note: Stale update check settings have been removed from thuBeaconGui.exe.config. The auto-update check is now per-connection profile (CheckForUpdates in connections.json), not global. All settings are in app.config or connections.json (no registry usage).

The Check for updates setting is stored per connection profile in connections.json (not in thuBeaconGui.exe.config). See Connection Profiles.

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
Update file distribution: Agent and GUI update files are uploaded to both servers independently by the GUI (not via HA replication). Server updates are deployed to each node separately (secondary first, then primary). This ensures immediate consistency without sync delay.
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!
HA shared secret	Warning logged on startup if `HaSharedSecret` is weak/default (< 12 chars or matches known defaults like "SomeSecret")
Credential encryption	AES-256-CBC encryption for credentials at rest — SMTP password (server), connection passwords (GUI)
Secrets masked	SmtpPassword, HaSharedSecret, CertificatePassword, EncryptionKey are masked in log and audit output
User auto-lockout	N banned IPs for same user → account locked (configurable, GlobalAdmin exempt)
Account expiry	Per-user expiry date (or "never")
Remote server update	Upload and apply new server binaries remotely via `UPLOAD_SERVER_UPDATE` / `APPLY_SERVER_UPDATE` (GlobalAdmin only)
Centralized update distribution	Upload and distribute agent and GUI updates from the server — agents update on next check-in, GUI users are prompted on connect when a newer version is available

Role-Based Access Control (RBAC)

Since version 1.4.3, thuBeacon supports role-based access control for admin users. Each user is assigned one of four roles:

Role	Scope	Access
Global Admin	All customers	Full access to all features: customers, locations, devices, messages, tokens, users, analytics, global settings
Global Notifier	All customers	Send notifications to any customer. No access to management features.
Customer Admin	Assigned customers	Full access to assigned customers: locations, devices, messages, analytics. No access to user management, token management, or global settings.
Customer Notifier	Assigned customers	Send notifications to assigned customers only. No other access.

User Profile Fields

Each admin user has the following profile fields:

Field	Description
Username	Login name (unique, case-insensitive)
Password	Salted hash, must meet configured password policy
Company	Company / organization name
Prename	First name
Name	Last name
Email	Email address
Role	One of: GlobalAdmin, GlobalNotifier, CustomerAdmin, CustomerNotifier
Customers	Comma-separated customer IDs (only for Customer-scoped roles)
Expires	Account expiry date (ISO 8601) or empty for "never expires"
Locked	Manual lock/unlock flag

GUI Tab Visibility by Role

Tab	Global Admin	Global Notifier	Customer Admin	Customer Notifier
Customers	✅	❌	✅ (read-only)	❌
Locations	✅	❌	✅	❌
Devices	✅	❌	✅	❌
Messages	✅	✅	✅	✅
Tokens	✅	❌	❌	❌
Users	✅	❌	✅ (CustomerNotifier only)	❌
Analytics	✅	❌	✅	❌

User Auto-Lockout

When a user account triggers N distinct banned IPs within the failure window (default: 5 IPs in 10 minutes), the account is automatically locked for AuthLockoutMinutes (default: 15 minutes). The lockout expires automatically.

GlobalAdmin accounts are never auto-locked (to prevent locking out the only admin)
The threshold is configurable via MaxBannedIpsBeforeUserLockout in thuBeaconServer.exe.config
Manual lock/unlock is available in the Users tab (GlobalAdmin only)
Account expiry is checked on every login attempt

Password Policy

The configured password complexity rules are enforced on the server when adding users or changing passwords. The current policy is displayed in the GUI's Users panel after connecting.

Password policy settings in thuBeaconServer.exe.config:

<add key="PasswordMinLength" value="8" />
<add key="PasswordRequireUppercase" value="true" />
<add key="PasswordRequireLowercase" value="true" />
<add key="PasswordRequireDigit" value="true" />
<add key="PasswordRequireSpecialChar" value="false" />

Migration from 1.4.2

Existing admins.json entries without a Role field are automatically migrated to GlobalAdmin on server startup. No manual intervention is needed.

Analytics Storage Management

Since version 1.4.3, Global Admins can manage analytics storage configuration and monitor disk usage via Settings → Analytics Storage in the GUI.

Settings

Setting	Description
Analytics Enabled	Enable/disable analytics collection
Retention Days	Number of days to keep analytics data (1–3650)
Log Retention	Enable automatic deletion of old analytics files at midnight
Analytics Folder	Custom storage folder path (default: `{DataFolder}\analytics`)
Default Date Range	Default date range (days) for analytics queries in the GUI

Storage Dashboard

The dashboard shows real-time disk usage information:

Metric	Description
Server Drive	The drive letter where analytics are stored
Total Disk Space	Total capacity of the drive
Free Disk Space	Available space on the drive
Analytics Storage Used	Current analytics folder size + file count
Predicted at Xd	Estimated storage at configured retention days
Predicted at X+365d	Estimated storage at retention + 1 year

Storage Chart

A line chart visualizes storage growth projections with separate series:

Series	Color	Description
Storage Used	Green (solid)	Current analytics storage usage
Predicted at Xd	Blue (solid)	Projected size at configured retention
Predicted at X+365d	Blue (dotted)	Projected size at retention + 1 year
Free Disk Space	Red (dashed)	Only shown when free space is within 3× of predicted growth

Log Retention

When Log Retention is enabled:

Old analytics files are automatically deleted daily at midnight
Files older than the configured retention days are removed
A warning dialog is shown when enabling retention or reducing retention days (potential data loss)
The "Apply Retention Now" button forces immediate cleanup (with confirmation)
The FORCE_ANALYTICS_RETENTION command returns the count of deleted and remaining files

Folder Change

When changing the analytics folder path:

A confirmation dialog asks whether to move existing files to the new location
If confirmed, the server moves all .json analytics files and re-initializes the analytics store
The new path is saved to thuBeaconServer.exe.config

Configuration

<add key="AnalyticsEnabled" value="true" />
<add key="AnalyticsRetentionDays" value="365" />
<add key="AnalyticsRetentionEnabled" value="false" />
<add key="AnalyticsDefaultDateRangeDays" value="30" />
<add key="AnalyticsFolder" value="" />

Key	Default	Description
`AnalyticsEnabled`	`true`	Enable analytics collection and storage
`AnalyticsRetentionDays`	`365`	Auto-delete analytics data older than N days
`AnalyticsRetentionEnabled`	`false`	Enable the daily midnight cleanup job
`AnalyticsDefaultDateRangeDays`	`30`	Default date range for GUI analytics queries
`AnalyticsFolder`	(empty)	Custom folder path (empty = `{DataFolder}\analytics`)

Server Settings (Remote Configuration)

Since version 1.4.3, Global Admins can view and modify all server appSettings remotely via Settings → Server Settings in the GUI — without manually editing thuBeaconServer.exe.config on the server.

Tabs

Tabs are sorted alphabetically:

Tab	Settings
Backup & Restore	Manual backup/restore, scheduled backups (local/CIFS), interval, time-of-day, backup log, include analytics option
HA Replication	Enable/disable HA, peer host/port, listen port, shared secret, sync interval, replicate analytics
Logging & Scheduler	Log folder, log retention days, scheduler interval, heartbeat timeout, admin session timeout
Network	Listen port, max message size (MB), encryption key
Security	Rate limiting (max failed auth, lockout minutes, failure window, banned IPs threshold, connections per IP, max concurrent), password policy (min length, require uppercase/lowercase/digit/special)
SMTP	SMTP server, port, TLS, username, password, sender address; "Send Test Email" button to verify configuration
TLS Certificate	View current certificate filename, upload a new PFX file, change certificate password
Update Agent	Upload agent executable and config template to server; agents receive updates on next check-in (GlobalAdmin only)
Update Gui	Upload: GlobalAdmin uploads GUI executable for distribution. Download: any admin can check for and apply GUI updates
Update Server	Upload and apply new server executable remotely; shows version, size, SHA256 hash; supports HA (GlobalAdmin only). Server updates apply immediately (no staged file).

Settings Deployment & Hot Reload

When saving server settings (with or without a new TLS certificate):

Settings are written to thuBeaconServer.exe.config on the server
If a new PFX certificate was selected, it is uploaded and the password saved
The server receives a RELOAD_CONFIG command — this hot-reloads the configuration and TLS certificate without restarting the process
A progress dialog shows 5 steps per server:
Saving settings
Uploading certificate (or "No new certificate")
Saving certificate password (or "Skipped")
Reloading configuration
Done

HA Mode: In an HA configuration, settings are deployed to the secondary server first, then the primary. Each server shows its own progress section. HA-specific keys (HaPeerHost, HaPeerPort, etc.) are never copied between servers — they are server-specific.

Note: The RELOAD_CONFIG command refreshes appSettings from disk and hot-swaps the TLS certificate. New connections use the new certificate; existing connections are unaffected. The TCP listener stays up throughout — no port drop, no downtime, no reconnection needed.

Settings That Require Full Restart

Most settings take effect via RELOAD_CONFIG. The following require a full server restart (use RESTART_SERVICE or restart the Windows service manually):

Setting	Reason
`ListenPort`	TCP listener is bound at startup
`MaxConcurrentConnections`	Semaphore is allocated at startup
`DataFolder`	Data store is initialized at startup

MaxMessageSize Management

The MaxMessageSizeMB setting controls the maximum size of a single protocol message between server and GUI. Large analytics queries can exceed this limit.

Auto-Sync

Since version 1.4.3, the GUI automatically fetches the server's MaxMessageSizeMB on connect and applies it locally. The value is saved to connections.json and the field in Connection Details is read-only (greyed out). This ensures server and GUI always use the same limit.

Smart Error Handling

When an analytics query exceeds the message size limit, the GUI shows a detailed dialog with:

Current configuration: MaxMessageSizeMB, AnalyticsRetentionDays
Analytics storage stats: folder size, file count, date range, estimated total at configured retention
Three options:
Increase — adds 10 MB to MaxMessageSizeMB on the server (updates config file, applies immediately without restart, syncs to GUI profile, then retries loading analytics)
Reduce date range — close the dialog and adjust the date pickers
Cancel — dismiss the dialog

Note: Only Global Admin users can increase the MaxMessageSizeMB. The change is audit-logged on the server.

HA Failover on Connect

Since version 1.4.3, the GUI tries the secondary server automatically when the primary is unreachable during the initial connection (including auto-connect on startup). Previously, failover only triggered after an established connection was lost. Authentication failures (wrong credentials) do not trigger failover.

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`
Server updates (agent)	`%ProgramData%\thuinformatik GmbH\thuBeacon\Server\updates\agent\`
Server updates (GUI)	`%ProgramData%\thuinformatik GmbH\thuBeacon\Server\updates\gui\`
Server updates (server)	`%ProgramData%\thuinformatik GmbH\thuBeacon\Server\updates\server\`
Server backups	`%ProgramData%\thuinformatik GmbH\thuBeacon\Server\backups\`
Server HA backup staging	`%ProgramData%\thuinformatik GmbH\thuBeacon\Server\backups\ha-staging\`
Backup schedule config	`%ProgramData%\thuinformatik GmbH\thuBeacon\Server\backup-schedule.json`
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.

Contact


Web	https://www.thu.ch
E-Mail	notify@thu.ch
Project	https://sourceforge.net/projects/thubeacon/
Developer	thuinformatik GmbH

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

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

Compatibility Matrix

How It Works

Architecture

TCP Ports

Data Model

Alert Messages

SMTP Email Notifications

Message Delivery Tracking

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

Loading Progress

Work Hours

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

Message Deliveries

Configuration: Non-HA (Single Server)

Server (thuBeaconServer.exe.config)

Server (`thuBeaconServer.exe.config`)

Agent (`thuBeaconAgent.exe.config`)

GUI (`thuBeaconGui.exe.config`)

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

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