.. _Known-Hosts-File:

================
Known Hosts File
================

Before an agent can connect to a VOLTTRON platform that agent must know the platform's :term:`VIP address` and public
key (known as the `server key`).  It can be tedious to manually keep track of server keys and match them with their
corresponding addresses.

The purpose of the known-hosts file is to save a mapping of platform addresses to server keys.  This way the user only
has to specify a server key one time.


Saving a Server Key
-------------------

Suppose a user wants to connect to a platform at ``192.168.0.42:22916``, and the platform's public key is
``uhjbCUm3kT5QWj5Py9w0XZ7c1p6EP8pdo4Hq4dNEIiQ``.  To save this address-to-server-key association, the user can run:

.. code-block:: bash

    volttron-ctl auth add-known-host --host 192.168.0.42:22916 --serverkey uhjbCUm3kT5QWj5Py9w0XZ7c1p6EP8pdo4Hq4dNEIiQ

Now agents on this system will automatically use the correct server key when connecting to the platform at
``192.168.0.42:22916``.


Server Key for Local Platforms
------------------------------

When a platform starts it automatically adds its public key to the known-hosts file.  Thus agents connecting to the
local VOLTTRON platform (on the same system and using the same ``$VOLTTRON_HOME``) will automatically be able to
retrieve the platform's public key.


Know-Host-File Details
----------------------

.. note::

    The following details regarding the known-hosts file are subject to change.  These notes are primarily for
    developers, but the may be helpful if troubleshooting an issue. **The known-hosts file should not be edited
    directly.**


File Location
^^^^^^^^^^^^^

The known-hosts-file is stored at ``$VOLTTRON_HOME/known_hosts``.


File Contents
^^^^^^^^^^^^^

Here are the contents of an example known-hosts file:

.. code:: JSON

    {
        "@": "FSG7LHhy3v8tdNz3gK35G6-oxUcyln54pYRKu5fBJzU", 
        "127.0.0.1:22916": "FSG7LHhy3v8tdNz3gK35G6-oxUcyln54pYRKu5fBJzU", 
        "127.0.0.2:22916": "FSG7LHhy3v8tdNz3gK35G6-oxUcyln54pYRKu5fBJzU", 
        "127.0.0.1:12345": "FSG7LHhy3v8tdNz3gK35G6-oxUcyln54pYRKu5fBJzU", 
        "192.168.0.42:22916": "uhjbCUm3kT5QWj5Py9w0XZ7c1p6EP8pdo4Hq4dNEIiQ" 
    }

The first four entries are for the local platform. (They were automatically added when the platform started.)  The first
entry with the ``@`` key is for IPC connections, and the entries with the ``127.0.0.*`` keys are for local TCP
connections. Note that a single VOLTTRON platform can bind to  multiple TCP addresses, and each address will be
automatically added to the known-hosts file.  The last entry is for a remote VOLTTRON platform.  (It was added in the
`Saving a Server Key`_ section.)