gNMIc on AWS User Guide

Overview

gNMIc is a self hosted, open source gNMI client and telemetry collector from OpenConfig. It speaks the gNMI management protocol to your routers and switches, supporting Capabilities, Get, Set and Subscribe, and as a collector it continuously streams operational telemetry from your devices into your observability stack: Prometheus, InfluxDB, Kafka, NATS, TCP, UDP and files. Targets, subscriptions, outputs and processors are all defined in plain YAML.

The cloudimg image installs the official gNMIc binary at /usr/local/bin/gnmic, running as the gnmic service in collector mode (gnmic subscribe) with its Prometheus output bound to loopback 127.0.0.1:9804 and its REST api-server bound to loopback 127.0.0.1:7890, behind nginx on port 80. nginx is ready for your TLS certificate.

Secure by default, no default login: gNMIc's metrics and api-server endpoints ship with no authentication of their own. This image never exposes them unauthenticated. The daemon binds both to loopback only and they are served through nginx: GET /health is an unauthenticated liveness endpoint for load balancer probes, while /metrics, /api/ and every other path require HTTP Basic Auth (username cloudimg). A gnmic-firstboot.service oneshot generates a unique password on each instance's first boot, writes it to a root only file and to an nginx htpasswd, resolves the instance URL and writes a root only info note, then disables itself. No two instances share a password and none is baked into the image.

Always current: on first boot the appliance downloads the newest gNMIc release binary (falling back to the baked version if the network is unavailable), so every launch runs current software rather than the version frozen at build time.

Note on the interface: gNMIc is a headless collector. It has no web UI; you drive it through its YAML configuration (/etc/gnmic/gnmic.yaml), its REST api-server and the gnmic command line, and it exposes telemetry through the outputs you enable. This guide uses curl against the metrics and api-server endpoints and edits the YAML config directly.

What is included:

• gNMIc (verified at 0.46.0) as the official self contained binary
• gnmic.service running gnmic subscribe with the Prometheus output on 127.0.0.1:9804 and the api-server on 127.0.0.1:7890
• nginx reverse proxy on port 80: public /health, password protected /metrics and /api/
• gnmic-firstboot.service for the first boot password, binary refresh and info note
• A unique per instance API password generated on first boot, in a root only 0600 file
• Ubuntu 24.04 LTS base, fully patched
• 24/7 cloudimg support, 24h response SLA

Connecting to your instance

SSH to the instance as the default login user for the AMI variant you launched. gNMIc is headless, so all administration is over SSH.

Prerequisites

An AWS account, an EC2 key pair, and a VPC with a subnet. gNMIc is lightweight and CPU friendly. Recommended instance type: m5.large (2 vCPU, 8 GB RAM) is sufficient for most deployments; use a larger type only if you collect from a very large number of targets or at a high sample rate. gNMIc dials out to your devices' gNMI port (commonly TCP 57400, 9339 or 6030), so allow outbound access from the instance to your network devices. No inbound gNMI port is required on the instance itself.

Step 1: Launch from the AWS Marketplace (EC2 console)

Find gNMIc in AWS Marketplace, subscribe, and launch. Choose your instance type (m5.large recommended), your key pair, and a security group that allows TCP 22 (SSH) from your management network and TCP 80 (the metrics and API endpoints) from the networks that need to scrape or manage the collector. Front port 80 with TLS in production (see the HTTPS section below). No inbound port is required for gNMIc to collect: it makes outbound connections to your devices.

Step 2: Launch from the AWS CLI

AMI_ID="<the-gnmic-ami-id>"          # from the Marketplace launch page for your Region
KEY_NAME="my-key"; SG_ID="sg-xxxxxxxx"; SUBNET_ID="subnet-xxxxxxxx"
aws ec2 run-instances \
  --image-id "$AMI_ID" --instance-type m5.large \
  --key-name "$KEY_NAME" --security-group-ids "$SG_ID" --subnet-id "$SUBNET_ID" \
  --metadata-options 'HttpTokens=required,HttpEndpoint=enabled' \
  --block-device-mappings '[{"DeviceName":"/dev/sda1","Ebs":{"VolumeType":"gp3"}}]' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=gnmic-01}]'

Step 3: Connect via SSH

ssh ubuntu@<public-ip>

Step 4: Verify the services are running

gNMIc's Prometheus output listens on loopback 127.0.0.1:9804 and its api-server on 127.0.0.1:7890; nginx fronts both on port 80. The health endpoint is public; the metrics and API endpoints require your password.

sudo systemctl is-active gnmic nginx
ss -tln | grep -E ':80 |127.0.0.1:9804|127.0.0.1:7890'
curl -s http://127.0.0.1/health

You should see both services active, the three listening sockets (the Prometheus output and the api-server bound to loopback, nginx on port 80), and ok from the public health endpoint.

active
active
LISTEN 0  4096  127.0.0.1:9804  0.0.0.0:*
LISTEN 0  511     0.0.0.0:80     0.0.0.0:*
LISTEN 0  4096  127.0.0.1:7890  0.0.0.0:*
ok

Step 5: Read your per instance API password

The password was generated on this instance's first boot and stored in a root only file. Read it and keep it secret: it authenticates every metrics and API request. Confirm that unauthenticated requests are rejected.

sudo cat /root/gnmic-info.txt
echo "unauthenticated /metrics -> HTTP $(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1/metrics)"

The info note holds API_PASSWORD and the instance URLs, is owned root:root with mode 0600, and an unauthenticated call to /metrics returns 401 because nginx enforces authentication.

Step 6: Query the metrics and the api-server

Load the password into a shell variable and query the endpoints through nginx with HTTP Basic Auth. The Prometheus /metrics endpoint is where your telemetry is exposed for scraping; it returns HTTP 200 and populates once a target streams data. The gNMIc REST api-server reports the configured targets and subscriptions as JSON.

export GNMIC_PW=$(sudo grep '^API_PASSWORD=' /root/gnmic-info.txt | cut -d= -f2-)
echo "authenticated /metrics                 -> HTTP $(curl -s -o /dev/null -w '%{http_code}' -u cloudimg:$GNMIC_PW http://127.0.0.1/metrics)"
echo "authenticated /api/v1/config/targets   -> HTTP $(curl -s -o /dev/null -w '%{http_code}' -u cloudimg:$GNMIC_PW http://127.0.0.1/api/v1/config/targets)"
curl -s -u cloudimg:$GNMIC_PW http://127.0.0.1/api/v1/config/subscriptions | jq .
curl -s -u cloudimg:$GNMIC_PW http://127.0.0.1/api/v1/config/targets | jq 'map_values({address, subscriptions})'

Both authenticated calls return 200. The api-server returns the interface-counters subscription (its paths and stream mode) and the configured target. This is the endpoint an automation system points at to add targets and subscriptions at runtime.

Step 7: Point gNMIc at your own devices

Out of the box the collector ships a placeholder target (your-target:57400) with a sample interface-counters subscription so the daemon runs immediately. Replace the target with your own gNMI capable device(s). Edit /etc/gnmic/gnmic.yaml, set the target address and credentials, then restart the collector. Substitute <your-domain> with your device's hostname or IP.

sudo sed -i 's/your-target:57400/<your-domain>:57400/' /etc/gnmic/gnmic.yaml
sudo sed -i 's/^username: admin/username: <your-domain-user>/' /etc/gnmic/gnmic.yaml
sudo systemctl restart gnmic

Each target is a host:port entry under targets: in the config; the global username, password, skip-verify and encoding apply to every target and can be overridden per target. Define your subscription paths (YANG/OpenConfig paths such as /interfaces/interface/state/counters) under subscriptions:. See the gNMIc documentation for the full configuration reference.

Step 8: Ad hoc gNMI requests with the CLI

Beyond the collector daemon, the full gnmic command line is available for one off Capabilities, Get and Set requests against any gNMI target. Substitute <your-domain> with your device.

gnmic -a <your-domain>:57400 -u admin -p 'your-device-password' --skip-verify capabilities
gnmic -a <your-domain>:57400 -u admin -p 'your-device-password' --skip-verify get --path /interfaces/interface/state/counters

capabilities lists the models, encodings and gNMI version the device supports; get performs a one shot read of a path. These are the same requests the collector makes under the hood.

Step 9: Scrape the metrics from Prometheus

Point your Prometheus server at the collector. Because the endpoint is password protected, use a basic_auth block in your scrape config (over HTTPS in production, see below).

scrape_configs:
  - job_name: gnmic
    metrics_path: /metrics
    basic_auth:
      username: cloudimg
      password: <the API_PASSWORD from /root/gnmic-info.txt>
    static_configs:
      - targets: ['<instance-public-ip>']

gNMIc also supports InfluxDB, Kafka, NATS, TCP, UDP and file outputs; add them under outputs: in /etc/gnmic/gnmic.yaml and reference them from your targets or subscriptions.

Step 10: Enable HTTPS

nginx fronts the metrics and API endpoints on port 80 and is ready for TLS. Point a DNS record at the instance, then obtain a certificate with certbot and let it configure nginx for port 443.

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d <your-domain>

After issuance, restrict the security group so only 443 (and 22 from your management network) is reachable, and scrape the metrics over https://<your-domain>/metrics with the password.

Persistence, first boot and updates

The collector configuration (/etc/gnmic/gnmic.yaml) lives on the OS disk and is captured into the image, so an instance launched from this image is ready immediately. The first boot service generates the per instance API password, refreshes the gNMIc binary to the latest release, then disables itself so subsequent reboots are unaffected. The OS ships fully patched with unattended security upgrades enabled.

Support

Every cloudimg deployment includes 24/7 support with a 24 hour response SLA. Contact support@cloudimg.co.uk for help with deployment, configuration or scaling.

This is a repackaged open source software product with additional charges for cloudimg support services. gNMIc is a trademark of its respective owner. All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.