Skip to main content

Getting Started

To get up and running quickly with Passport, we will be installing the Agent Manager on a Linux or macOS host for it to manage existing supported collection agents.

  1. Install any of Passport's supported collection agents.
  2. Install and register the Agent Manager
  3. Import and assign a configuration file to your Agent Manager..
  4. Optional:
    1. Create rules for your configuration files if you have more than 1 configuration file uploaded.
    2. Add external alerts so you can trigger rules to modify when specific configurations will be enabled.

Install and register the Agent Manager​

Supported Platforms​

info

If the following guided installation doesn't fit your environment, please review the available Agent Manager packages on the GitHub packages release page.


Step 1 - Add the Manager Repo and Install
  • Note: Regardless of the Ubuntu or Debian version or name, use the following commands to install the Manager.
amd64
sudo wget -O /etc/apt/trusted.gpg.d/circonus.asc https://keybase.io/circonuspkg/pgp_keys.asc?fingerprint=14ff6826503494d85e62d2f22dd15eba6d4fa648 &&
echo "deb http://updates.circonus.net/ubuntu/ jammy main" | sudo tee -a /etc/apt/sources.list.d/circonus.list &&
sudo apt update && sudo apt install circonus-am
Step 2 - Register, restart and view the status

  • Navigate to Passport > Agent Management > Registration to retrieve a valid registration token secret and replace <registrationTokenSecret> with your account registration token secret and then run the following terminal command.

    • Note: This secret can not be retrieved again once the window is closed and a new one will need to be created, so keep this for future use.

  • Agent Manager Tagging - Optional

    • Tags can be added only during registration times by using the --tags flag either before or after the --register flag.
    • If tags need to be added after the initial registration, re-register your agent manager again with the desired tags.
    • Ex: CLI tags: --tags="foo:bar,baz:qux" with , separating the key:val entries.
    • Ex: Environment variables: CAM_TAGS="foo:bar baz:qux" with spaces separating the key:val entries.
sudo /opt/circonus/am/sbin/circonus-am --register="<registrationTokenSecret>" &&
sudo systemctl restart circonus-am &&
sudo systemctl status circonus-am
SUCCESS!

If the registration is successful, then you will see "message": "registration complete" from the Agent Manager and also the status of its service as Active: active (running).

Example - Successful installation

Linux Ubuntu
# Step 1
circonus@ubuntu-host:/etc/apt/sources.list.d$ sudo wget -O /etc/apt/trusted.gpg.d/circonus.asc https://keybase.io/circonuspkg/pgp_keys.asc?fingerprint=14ff6826503494d85e62d2f22dd15eba6d4fa648 &&
echo "deb http://updates.circonus.net/ubuntu/ jammy main" | sudo tee -a /etc/apt/sources.list.d/circonus.list &&
sudo apt update && sudo apt install circonus-am
--2023-09-22 14:14:42--  https://keybase.io/circonuspkg/pgp_keys.asc?fingerprint=14ff6826503494d85e62d2f22dd15eba6d4fa648
Resolving keybase.io (keybase.io)... 52.3.107.250, 52.72.123.132
Connecting to keybase.io (keybase.io)|52.3.107.250|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 3122 (3.0K) [text/plain]
Saving to: ‘/etc/apt/trusted.gpg.d/circonus.asc’

/etc/apt/trusted.gpg.d/circonus.asc 100%[===================================================================>]   3.05K  --.-KB/s    in 0s

2023-09-22 14:14:42 (773 MB/s) - ‘/etc/apt/trusted.gpg.d/circonus.asc’ saved [3122/3122]

deb http://updates.circonus.net/ubuntu/ jammy main
Hit:1 http://us-central1.gce.archive.ubuntu.com/ubuntu jammy InRelease
Hit:2 http://us-central1.gce.archive.ubuntu.com/ubuntu jammy-updates InRelease
Hit:3 http://us-central1.gce.archive.ubuntu.com/ubuntu jammy-backports InRelease
Hit:4 http://security.ubuntu.com/ubuntu jammy-security InRelease
Hit:5 https://download.docker.com/linux/ubuntu jammy InRelease
Hit:6 http://updates.circonus.net/ubuntu jammy InRelease
Hit:7 https://packages.fluentbit.io/ubuntu/jammy jammy InRelease
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
78 packages can be upgraded. Run 'apt list --upgradable' to see them.
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following NEW packages will be installed:
  circonus-am
0 upgraded, 1 newly installed, 0 to remove and 78 not upgraded.
Need to get 4281 kB of archives.
After this operation, 10.7 MB of additional disk space will be used.
Get:1 http://updates.circonus.net/ubuntu jammy/main amd64 circonus-am amd64 0.2.9 [4281 kB]
Fetched 4281 kB in 1s (5300 kB/s)
Selecting previously unselected package circonus-am.
(Reading database ... 124909 files and directories currently installed.)
Preparing to unpack .../circonus-am_0.2.9_amd64.deb ...
Unpacking circonus-am (0.2.9) ...
Setting up circonus-am (0.2.9) ...
Created symlink /etc/systemd/system/multi-user.target.wants/circonus-am.service → /lib/systemd/system/circonus-am.service.
Scanning processes...
Scanning candidates...
Scanning linux images...

Restarting services...
Service restarts being deferred:
 /etc/needrestart/restart.d/dbus.service
 systemctl restart docker.service
 systemctl restart networkd-dispatcher.service
 systemctl restart unattended-upgrades.service

No containers need to be restarted.

No user sessions are running outdated binaries.

No VM guests are running outdated hypervisor (qemu) binaries on this host.

# Step 2
circonus@ubuntu-host:/etc/apt/sources.list.d$ sudo /opt/circonus/am/sbin/circonus-am --register="eyJhbGciOiJIUzUxMiIsImtpZCI6IjIzMzAyNjE2ODMwMTgyMDY3NSIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsiY29uZmlndXJhdGlvbnMtYXBpIl0sImNpcmNvbnVzOmFjY291bnQiOiJwcm9kdGVzdGluZyIsImNpcmNvbnVzOmdyYW50cyI6WyJjdXN0b21lcl9wYXNzcG9ydHJlZ2lzdGVyIl0sImNpcmNvbnVzOm9yZ2lkIjoiMjMzMDI2MTY4MzAxODIwNjc1IiwiY2lyY29udXM6dG9rZW4iOiIxYjMwNDViMC1lZjA4LTQ0NDMtOGYwYi0wMDZmNTNjOTdmMzQiLCJleHAiOjIwMTA5NzA3NjQsImlhdCI6MTY5NTM5NDc2NSwiaXNzIjoiY29uZmlndXJhdGlvbnMtYXBpIiwibmJmIjoxNjk1Mzk0NzY1LCJzdWIiOiIwIn0.BtN3jnlv78Ib0Dd5M3wQExlvokiobj3NBEkajRLQ6F9PgugmpxkCVgr2bGHXV6Kav-DopSFjVV31jOxjgz0oCg" --tags="os:linux_deb" && sudo systemctl restart c
irconus-am && sudo systemctl status circonus-am
{"level":"info","cfg_file":"/opt/circonus/am/etc/circonus-am.yaml","time":1695395093,"message":"config file found/used"}
{"level":"info","name":"circonus-am","version":"0.2.9","time":1695395093,"message":"starting"}
{"level":"info","time":1695395093,"message":"starting registration"}
{"level":"warn","file":"/usr/bin/newrelic-infra-service","time":1695395093,"message":"agent binary not found, skipping"}
{"level":"warn","file":"/usr/bin/otelcol","time":1695395093,"message":"agent binary not found, skipping"}
{"level":"info","agent":"telegraf","time":1695395093,"message":"found"}
{"level":"info","agent":"cua","time":1695395093,"message":"found"}
{"level":"warn","file":"/usr/bin/datadog-agent","time":1695395093,"message":"agent binary not found, skipping"}
{"level":"warn","file":"/usr/share/filebeat/bin/filebeat","time":1695395093,"message":"agent binary not found, skipping"}
{"level":"info","agent":"fluent-bit","time":1695395093,"message":"found"}
{"level":"warn","file":"/usr/share/metricbeat/bin/metricbeat","time":1695395093,"message":"agent binary not found, skipping"}
{"level":"warn","file":"/usr/bin/vector","time":1695395093,"message":"agent binary not found, skipping"}
{"level":"info","pkg":"manager","time":1695395093,"message":"registration complete"}
● circonus-am.service - Circonus Agent Manager
     Loaded: loaded (/lib/systemd/system/circonus-am.service; enabled; vendor preset: enabled)
     Active: active (running) since Fri 2023-09-22 15:04:53 UTC; 23ms ago
       Docs: https://github.com/circonus/agent-manager
   Main PID: 1249575 (circonus-am)
      Tasks: 6 (limit: 9525)
     Memory: 1.4M
        CPU: 4ms
     CGroup: /system.slice/circonus-am.service
             └─1249575 /opt/circonus/am/sbin/circonus-am --config=/opt/circonus/am/etc/circonus-am.yaml

Video Tutorial​


Managing additional collection agents​

If additional agents have been added to the host where Agent Manager is running, then you will need to run a few CMDs for them to become discovered.

Take an inventory of local collection agents
Example: stop, re-inventory, start and view the Agent Manager's status
sudo systemctl stop circonus-am &&
sudo /opt/circonus/am/sbin/circonus-am --inventory &&
sudo systemctl start circonus-am &&
sudo systemctl status circonus-am
Success

Example of what the output will look like when a telegraf agent has been found.

{"level":"info","agent":"telegraf","time":1692044346,"message":"found"}
{"level":"info","pkg":"manager","time":1692044346,"message":"inventory complete"}
Example - Successful re-inventory

Linux Ubuntu
ubuntu-host:~$ sudo systemctl stop circonus-am &&
sudo /opt/circonus/am/sbin/circonus-am --inventory &&
sudo systemctl start circonus-am &&
sudo systemctl status circonus-am
{"level":"info","name":"circonus-am","version":"0.2.3","time":1694466173,"message":"starting"}
{"level":"warn","error":"exit status 127","agent":"cua","time":1694466174,"message":"getting agent version"}
{"level":"info","agent":"cua","time":1694466174,"message":"found"}
{"level":"warn","file":"/usr/share/filebeat/bin/filebeat","time":1694466174,"message":"agent binary not found, skipping"}
{"level":"warn","file":"/usr/bin/otelcol","time":1694466174,"message":"agent binary not found, skipping"}
{"level":"warn","file":"/usr/bin/vector","time":1694466174,"message":"agent binary not found, skipping"}
{"level":"warn","file":"/usr/sbin/datadog-agent","time":1694466174,"message":"agent binary not found, skipping"}
{"level":"info","agent":"fluent-bit","time":1694466174,"message":"found"}
{"level":"warn","file":"/usr/share/metricbeat/bin/metricbeat","time":1694466174,"message":"agent binary not found, skipping"}
{"level":"warn","file":"/usr/bin/newrelic-infra-service","time":1694466174,"message":"agent binary not found, skipping"}
{"level":"info","agent":"telegraf","time":1694466175,"message":"found"}
{"level":"info","pkg":"manager","time":1694466175,"message":"invetory complete"}
● circonus-am.service - Circonus Agent Manager
     Loaded: loaded (/lib/systemd/system/circonus-am.service; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2023-09-11 21:02:55 UTC; 20ms ago
       Docs: https://github.com/circonus/agent-manager
   Main PID: 3323503 (circonus-am)
      Tasks: 7 (limit: 9525)
     Memory: 2.6M
        CPU: 4ms
     CGroup: /system.slice/circonus-am.service
             └─3323503 /opt/circonus/am/sbin/circonus-am --config=/opt/circonus/am/etc/circonus-am.yaml

Complete instructions to inventory new agents, uninstall, and troubleshoot can be found on the full Agent Manager page.

Import a configuration file​

The following instructions outline how to add configuration files from the Circonus UI to your account located in the main menu Passport > Configurations.

From the configurations list page, select Import.

configurations-import

Keep in mind

By default, when a configuration file is added to your Circonus account, it is not being managed by the Agent Manager until you assign it to a specific Agent Manager.

You have the option to upload a local file or simply paste the configuration in the code block. Fill in the rest of the form and select Import.

flow builder

Once the configuration file is imported, it will be displayed on the Passport > Configurations list page.

NOTE

Complete instructions to import and build configuration files with the low-code builder can be found on the full Configuration Files page.

Assign a configuration file​

After the Agent Manager has been installed and some collection agents are now being managed, you can start assigning configuration files to the collection agents under management.

note

If the Agent Manager is Disconnected during this process, once it comes back online it will pull down any assigned configs.

Configuration assignment statuses:

  • New (Recently assigned to an Agent Manager and the config is waiting for the next check-in from the Agent Manager which is every minute.)
  • Active (The Agent Manager has updated the configuration file for the selected collection agent)
  • Pending (The Agent Manager is in the process of applying the configuration)
  • Error (The Agent Manager encountered an error applying the configuration)
  • Canceled (The assignment was replaced by another new assignment before the Agent Manager had a chance to see it)
  • Inactive (The assignment was previously active but has now been replaced)

Assigning a configuration file can either be done from the specific file's details page or the Agent Manager page.

configurations-assign-both-ways

Configuration details page​

From a Passport > Configurations details page, select the Assign button to view all possible agents that can be assigned this configuration.

configurations-assign

Agent Manager page​

Assign configuration file

All supported agent-type configuration files will be listed. Choose one and select Assign.

Assign configuration file

Next, the assignment will be pulled down by the Agent Manager on its next check which is every 60 seconds. When the configuration file has been updated on the collection agent, the status will change to Active.

If the Agent Manager is currently Disconnected, when it next checks in it will pull down the new config file.

Assign configuration file

Complete instructions for configuration files can be found on the Configuration file page.

Create rules​

Navigate to the Passport > Configurations list view, and select the configuration file to navigate to the details section.

Next, you can view details, preview the config file and create rules.

Select the Rules tab, and then click on the Create Rule button located at the top right of the table

Configurations Rules Tab

From here, you will define a rule to then be applied to this specific configuration file. Fully define the required fields and click Create.

DANGER

If you are creating alert-based rules, ensure the rules align with your expected outcome of the configuration assignment.

Configurations Rules Tab

All created rules will be listed in the Rules tab and if more than 1 rule has been created, they can be ordered to specify which rule has the most importance.

Rules ordering

The rules can be ordered by clicking and holding each rule on the far left side of the listed row and dragging it.

Complete instructions for Rules can be found on the rules engine page.

Add external alerts​

External Alerts are for you to add incoming alerts from outside sources such as Grafana, by using webhooks so you can create rules based on these events to then select which configuration files you want running on your collection agents.

Navigate to Passport > External Alerts and select Create External Alerts to get started.

External Alerts List View

Complete instructions for managing external alerts can be found on the external alerts page.