Skip to content

Enabling Known Host authentication for secure connections to agent stations

To strengthen the connection against man-in-the-middle attacks - without the need to create custom certificates - you can enable the known hosts check on the server.

  1. Stop the VDog MasterService.
  2. Open the server.ini file located in the server archive (VD$A\Configuration\Server.ini).

  3. In the [Common] section, add the following entry:

    KnownHostsOnCsc=Y

  4. Restart the VDog MasterService.

Once enabled, the server will verify the agent station's certificate fingerprint during job execution. If the fingerprint does not match, the connection is terminated and an error is logged.

Error message examples:

"The authenticity of host 'my.agentstation.local' cannot be established. The fingerprint of the certificate is '00:01:02:03:04:05:06:07:08:09:0a:0b:0c:0d:0e:0f:10:11:12:13:14:15:16:17:18:19:1a:1b:1c:1d:1e:1f'. Please contact your system administrator."

"Connect to agent station 'my.agentstation.local' fails because its certificate has been changed unexpectedly. Please validate if fingerprint in the servers entry in knownhosts.txt matches the one the agent stations dump into their Debug logfiles on startup."

If you see an error message like this, it means the agent's certificate does not match the certificate expected by the server.

To analyze the problem, proceed as follows:

  1. Check whether the fingerprint in the error message matches the one actually used by the agent station.

    The agents write their fingerprint to their debug log.

  2. On the agent computer, open the relevant log files in the agent archive from the time the agent was (re)started.

    • VD$A\Logs\Debug\VDogUploadAgent or
    • VD$A\Logs\Debug\VDogCompareAgent

    If needed, restart the agents to regenerate logs.

  3. In the log files, search for a line similar to:

    "Server's certificate has fingerprint 00:01:02:03:04:05:06:07:08:09:0a:0b:0c:0d:0e:0f:10:11:12:13:14:15:16:17:18:19:1a:1b:1c:1d:1e:1f".

Recognizing false alarms

The fingerprint in the log files of the agent computer must match the one from the server's error message above.

  • If the fingerprints do not match, this means that the server does not establish a direct connection to this agent.

    This type of mismatch may have a legitimate cause. For example, if a firewall is legally configured to intercept and inspect encrypted traffic that uses TLS (Transport Layer Security). If you're unsure whether this applies, consult your network administrator.

    Also, verify that the address configured for the agent on the server actually corresponds to the correct agent station.

    Warning

    If there is no valid reason for the mismatch, it may indicate a potential man-in-the-middle attack.

  • If the fingerprint matches or you're certain there's a valid reason for the mismatch but you still receive this error message, it's likely that the agent's certificate was recently changed or recreated. For example, if the agent has been reinstalled with a new agent archive.

    In this case (and only then!) remove this agent station from the server's KnownHosts.txt file:

    1. In the server archive, open the VD$A\Configuration\Local\KnownHosts.txt file with a text editor.

    2. Locate and delete lines related to the affected agent.

      Examples:

      my.agentstation.local 64011 4F4EA3E046F95327373587C3D1DB2537866A8D59765D00AD82256A6F5A19808B my.agentstation.local 64010 4F4EA3E046F95327373587C3D1DB2537866A8D59765D00AD82256A6F5A19808B

    3. Save the file. A server restart is not required.

    4. Reconnect to verify that the error no longer occurs.
    5. After a successful connection, the server will regenerate the KnownHosts.txt file with the correct fingerprint.

Related topics