Operation¶
If critical errors occur during operation or startup, they are systematically reported through the following interfaces:
- The web interface dashboard
- The engine's console (directly after logging in)
- The engine's system journal or log files
- The component executable's output when started in foreground mode.
Debugging Outputs¶
For diagnostic or troubleshooting purposes, any ControlGuard vX component executable can be started in the foreground with configurable logging verbosity. This mode displays real-time output directly on the terminal, enabling immediate visibility into startup behavior, configuration issues, or operational errors.
Performance Hit
When the debug logging level is used, the performance may be significantly impacted due to the generation of large volumes of verbose output. This logging level should therefore be used with caution and only when necessary.
Here is an example of debug-level output from the engine when direct console output is enabled using the --logtype console command-line parameter and the logging level is set to debug:
[root@controlguard-engine /]$ /opt/controlguard/bin/VXEngine --logtype console --loglevel debug
[03-12-2025 16:04:54] [pid:3178218] [debug] [apm] Host fingerprint: adad4c755a26ae7a
[03-12-2025 16:04:54] [pid:3178218] [debug] [apm] Control server public key successfully loaded
[03-12-2025 16:04:54] [pid:3178218] [debug] [apm] Key pair successfully loaded
[03-12-2025 16:04:54] [pid:3178218] [debug] [apm] Digital signature verification success
[03-12-2025 16:04:54] [pid:3178218] [debug] [apm] This license expire on 2026-01-01 00:00:00
[03-12-2025 16:04:54] [pid:3178218] [warning] Unix-domain local socket file already exists
[03-12-2025 16:04:54] [pid:3178218] [info] File build/aggregator.sock successfully deleted
[03-12-2025 16:04:54] [pid:3178218] [debug] Starting monitoring thread...
[03-12-2025 16:04:54] [pid:3178218] [debug] Starting control interface thread...
[03-12-2025 16:04:54] [pid:3178218] [debug] Starting database interface thread...
[03-12-2025 16:04:54] [pid:3178218] [debug] Monitoring thread successfully started
[03-12-2025 16:04:54] [pid:3178218] [debug] Control interface thread successfully started
[03-12-2025 16:04:54] [pid:3178218] [debug] Database interface thread successfully started
[03-12-2025 16:04:54] [pid:3178218] [debug] Creating database instance...
[03-12-2025 16:04:54] [pid:3178218] [error] Error while creating database instance: Cannot open database file: db/engine.db
[...]
The output above illustrates the startup sequence of the CountolGuard vX engine, followed by an error that occurs when attempting to open the database file. This error is typically caused by the file being accidentally deleted or by insufficient filesystem permissions.
Most connectors support foreground execution with debug logging enabled. The following example shows a Squid Connector instance launched with the logging level set to debug (using the --loglevel parameter) and the output directed to the console (using the --logtype console command-line parameter):
[root@controlguard-squidconnector /]$ /opt/controlguard/bin/squid-helper --logtype console --loglevel debug
[03-12-2025 16:05:12] [pid:3178293] [debug] Establishing connection to aggregator host 172.17.0.1:11224...
[03-12-2025 16:05:12] [pid:3178293] [debug] Starting watchdog thread...
[03-12-2025 16:05:12] [pid:3178293] [debug] Building authentication (init) message
[03-12-2025 16:05:12] [pid:3178293] [debug] Watchdog thread successfully started
[03-12-2025 16:05:12] [pid:3178293] [debug] Registering newly created session (sptr:0x7f6d777fbcb0)
[03-12-2025 16:05:12] [pid:3178293] [info] Successfully connected to aggregator host 172.17.0.1:11224
[03-12-2025 16:05:12] [pid:3178293] [debug] Sent 568/568 bytes message to aggregator host 172.17.0.1:11224
[03-12-2025 16:05:12] [pid:3178293] [debug] Read 566 bytes from aggregator host 172.17.0.1:11224
[03-12-2025 16:05:12] [pid:3178293] [debug] Received authentication (challenge) message from aggregator
[03-12-2025 16:05:12] [pid:3178293] [debug] Starting aggregator authentication...
[03-12-2025 16:05:12] [pid:3178293] [debug] Authentication response (peer): 71f610bab2dc4bf0b7218318f32c0e2e5aaea748ef76d94f292114270d141d59
[03-12-2025 16:05:12] [pid:3178293] [debug] Authentication response (local): 71f610bab2dc4bf0b7218318f32c0e2e5aaea748ef76d94f292114270d141d59
[03-12-2025 16:05:12] [pid:3178293] [debug] Aggregator authentication successful
[03-12-2025 16:05:12] [pid:3178293] [debug] Building authentication (response) message
[03-12-2025 16:05:12] [pid:3178293] [debug] Sent 568/568 bytes message to aggregator host 172.17.0.1:11224
[03-12-2025 16:05:12] [pid:3178293] [debug] Read 566 bytes from aggregator host 172.17.0.1:11224
[03-12-2025 16:05:12] [pid:3178293] [debug] Received authentication (confirm) message from aggregator
[03-12-2025 16:05:12] [pid:3178293] [debug] Building open message
[03-12-2025 16:05:12] [pid:3178293] [debug] Sent 320/320 bytes message to aggregator host 172.17.0.1:11224
[03-12-2025 16:05:12] [pid:3178293] [debug] Read 48 bytes from aggregator host 172.17.0.1:11224
[03-12-2025 16:05:12] [pid:3178293] [debug] Received openconfirm message from aggregator
[03-12-2025 16:05:12] [pid:3178293] [info] Session with aggregator (id:1) established
[03-12-2025 16:05:12] [pid:3178293] [debug] Starting SSL/TLS session handshake...
[03-12-2025 16:05:12] [pid:3178293] [debug] SSL/TLS session handshake completed
[03-12-2025 16:05:12] [pid:3178293] [debug] Using SSL/TLS protocol version: TLSv1.3, negociated cipher: TLS_AES_256_GCM_SHA384
[03-12-2025 16:05:12] [pid:3178293] [debug] Sent 72/72 bytes message to aggregator host 172.17.0.1:11224
[03-12-2025 16:05:12] [pid:3178293] [debug] Read 8536 bytes from aggregator host 172.17.0.1:11224
[03-12-2025 16:05:12] [pid:3178293] [debug] Received response message (seq:0)
[03-12-2025 16:05:12] [pid:3178293] [debug] Waiting for a message to transmit...
[...]
The output above demonstrates the connector attempting to establish a connection to the engine, initializing its various subsystem threads, performing authentication, and subsequently upgrading the session to use TLS encryption.