Linux Agent Setup

Time & NTP

Before you get too far, check to make sure your hyperglass server and hyperglass-agent system are both properly synchronized with an NTP server. During the setup process and on every interaction, hyperglass and hyperglass-agent exchange JWT tokens with a relatively short window (60 seconds, by default) in which to validate the payload. If the system clock on either system is askew by too much, this exchange can fail.

Setup

To automatically create an application directory, generate SSL certificates, generate and symlink a systemd file, and generate a random secret, run:

$ hyperglass-agent setup

During the setup process, you'll be prompted to:

  • Select an installation directory.
    Must be /etc/hyperglass-agent or ~/hyperglass-agent
  • Update hyperglass's devices.yaml file with a generated secret
  • Verify the hostname of the device.
    The hostname you verify is used to generate the agent's SSL certificate, and needs to be DNS-resolvable by hyperglass.
  • Select IP addresses from the device's interfaces that hyperglass would use to communicate with the agent.
    The IP addresses are added as Subject Alternative Names to the generated SSL certificate, so that you can point hyperglass to the agent by IP address if needed, but still leverage SSL validation.
  • Enter the URL of your hyperglass.
    hyperglass-agent will send the public key of your SSL certificate to hyperglass, so that future communication between hyperglass and hyperglass-agent is authenticated and encrypted.

After these prompts, the agent's SSL public & private keys and a configuration file will be generated and saved to your installation directory. A systemd service file will also be generated, saved to your installation directory, and symlinked to /etc/systemd/system/hyperglass-agent.service.

note

You can also run the setup wizard with certain options disabled, if needed:

$ hyperglass-agent setup --help
Usage: hyperglass-agent setup [OPTIONS]
Run the setup wizard
Options:
--no-config Don't regenerate config file
--no-certs Don't regenerate certificates
--no-systemd Don't generate a systemd file
--no-send Don't send the SSL certificate to hyperglass
--force Force regeneration of config file
-h, --help Show this message and exit.
More coming soon

Documentation for hyperglass-agent is in progress!