Linux Agent Setup

Deprecation Warning

hyperglass-agent is going to be deprecated soon. See Issue #143 and here for more detail.

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!