Components¶

ControlGuard vX has been specifically engineered for seamless configuration, requiring only minimal setup to become fully operational.

When using our official VMware or Docker installations, the engine is preconfigured to accept connections from the already installed squid connector instances, which are also preconfigured. As a result, no additional configuration is required for standard operation.

If you wish to add further connector instances to an existing installation, please refer to the relevant sections below for the configuration steps applicable to each component or service.

Engine¶

To enable ControlGuard vX Engine to accept connections and process requests, at least one connector must be configured.

The following example defines two connectors: local and remote. The local connector operates on the same host as the engine, while the remote connector runs on a separate host.

[connectors]

[connectors.local]
host = "localhost"
ip = "127.0.0.1"
key = "pleasechangethiskey" # (1)!

[connectors.remote]
host = "remote"
ip = "172.16.1.1"
key = "1234567secret" # (1)!

This attribute is mandatory and must be explicitly configured with identical values on both sides of the peer relationship. Please see the Peer Authentication section below for more details.

Each connector must include the mandatory ip parameter, which specifies the IP address on which the connector listens. In the example above, both connectors use the default transport protocol (tcp) and are assigned a unique shared authentication key via the key attribute.

The engine can now accept new connections and process requests from the connectors.

Connectors¶

Squid Connector¶

Each connector must be configured with the information of the ControlGuard Engine service. The only mandatory parameter is host, which specifies the remote address or hostname of the engine's host. In the example below, the connector is configured to connect to the engine located at the IP address 172.16.1.2:

[engine.remote]
host = "172.16.1.2"
key = "pleasechangethiskey"

Peer Authentication¶

Peer authentication prevents session hijacking, protects against denial-of-service (DoS) attacks, and provides additional layers of defense against unauthorized access, information disclosures and man-in-the-middle threats.

Peer Authentication is Mandatory

By default, ControlGuard vX enforces mutual peer authentication between the engine and the connectors. For this reason, the key attribute is mandatory and must be explicitly configured.

Configuration File Permissions

Ensure that the configuration files are not readable by unauthorized users. By default, they are readable only by the root user and members of the controlguard group. It is strongly recommended to enforce these restrictive filesystem permissions (typically 640 or stricter) and to verify that no world permissions are granted.

Missing Key Attribute

The ControlGuard Engine will not generate any warnings or errors if the key attribute is omitted from a connector’s configuration. The absence of this mandatory authentication key will silently prevent the connector from establishing a secure connection with the engine.

It is critical that the authentication key, provided by the key attribute, exactly matches (case-sensitive) in both locations:

In the engine’s connector configuration block
In the corresponding connector’s configuration file.

Any discrepancy between these two values will prevent successful authentication and establishment of the connection.