Osprey User Guide

Network Visibility & Engineering Platform

Osprey helps you explore network topology, monitor interface traffic, investigate routing changes, and test failure scenarios. It discovers OSPF, IS-IS, EIGRP, BGP, and Layer 2 neighbors, and brings the results together in one web interface.

Use this guide to set up discovery, work with the topology canvas and reports, or administer your installation. Each topic explains where to open the feature, how to use it, and how to interpret its results.

Getting Started
Dashboard
Setting Up Topology Discovery
The Topology Canvas
View Controls
Device & Link Inspection
Reports
Tools
Alerts & Incidents
SSH Terminal
Administration
Keyboard Shortcuts
Configuration Reference
Troubleshooting

1. Getting Started

Installation

Debian Package (recommended for production)

The package has a hard dependency on nats-server. On Debian 13 (Trixie), apt resolves it automatically from the distribution repository. On Debian 12 (Bookworm) and Ubuntu releases where that package is not available in the configured repositories, install a compatible nats-server package manually before installing Osprey, then verify it:

command -v nats-server

Then install Osprey:

sudo apt install ./osprey_<version>_amd64.deb

After all package dependencies are available, the installer:

Installs PostgreSQL, nginx, and the other declared dependencies
Creates the osprey system user and database
Generates a random database password, JWT secret, and encryption key (stored in /etc/osprey/osprey.env)
Creates a self-signed TLS certificate (valid for 10 years, stored in /etc/osprey/certs/)
Runs all database migrations
Enables the nginx site and removes the default site to avoid port conflicts
Starts all five Osprey services via systemd (osprey-engine, osprey-api, osprey-collector-manager, osprey-snmp-poller, osprey-bmp-server) under osprey.target

After installation you will see a summary:

Osprey installed successfully.
  Web UI:  https://localhost/
  Login:   admin / admin
  Config:  /etc/osprey/osprey.yaml
  Secrets: /etc/osprey/osprey.env
  Status:  systemctl status osprey.target

The Login: line is shown only on a first install, when the default admin / admin credentials are still in effect. On upgrades — or any time the admin password has already been changed — it instead reads use your existing admin credentials, so the summary never advertises a password that no longer works.

Tip: The .deb package works on Debian 12 (Bookworm), Debian 13 (Trixie), and Ubuntu 24.04+.

LXC Containers (Proxmox)

Osprey runs in both privileged and unprivileged LXC containers.

Privileged LXC — no special configuration needed. Install the .deb package as on bare metal.

Unprivileged LXC — requires nesting for systemd. Add to /etc/pve/lxc/<CTID>.conf:

features: nesting=1

GRE recorders create tunnel interfaces via netlink and capture packets with raw sockets. On kernel 6.x, CAP_NET_ADMIN and CAP_NET_RAW within the container's user namespace are sufficient — both are kept by default in Proxmox unprivileged containers. If GRE tunnel creation fails with a permission error, AppArmor may be blocking netlink operations. Resolve by adding:

lxc.apparmor.profile: unconfined

SNMP-only deployments (no GRE tunnels) work in unprivileged containers without any extra configuration beyond nesting=1.

Upgrading

When upgrading Osprey (installing a newer .deb package):

The postinst script automatically runs database migrations.
All five services are restarted.
Existing configuration in /etc/osprey/osprey.yaml and /etc/osprey/osprey.env is preserved (these are conffiles).
If a migration fails, the error is printed but the package install continues. Run migrations manually after fixing the issue.

Existing IS-IS crawlers are not converted during an upgrade: a parent bootstraps only with its own Bootstrap strict per-area recorders opt-in, which is added by default to new multi-level recorders only. The shipped configuration enables the global snmp.isis_bootstrap_enabled switch. An upgrade replaces an unmodified osprey.yaml. For an edited file, dpkg asks which version to keep; its default keeps your file and its value. For an unattended upgrade, pass --force-confdef --force-confold so dpkg takes that default without asking. A missing key leaves the switch off. Before downgrading after a completed IS-IS handoff, follow the rollback procedure in IS-IS bootstrap to strict per-area recorders.

When upgrading a release that left completed IS-IS bootstrap children read-only, Osprey checks each group before giving it normal management controls. Recorder changes can briefly wait during this conversion. If a request times out, check the result before submitting it again.

A child group that fails validation remains Managed. Check the collector-manager log and, if using Prometheus, osprey_manager_isis_bootstrap_ownership_pending.

# Upgrade
sudo apt install ./osprey_<new-version>_amd64.deb

# Verify the target and all five services after upgrade
systemctl status osprey.target 'osprey-*.service'

# If migrations failed, run manually
source /etc/osprey/osprey.env
/usr/bin/osprey migrate --db-url "postgres://osprey:${OSPREY_DB_PASSWORD}@localhost:5432/osprey?sslmode=disable"

Open your browser to https://your-server/ (port 443). Accept the self-signed certificate warning. Log in with the default credentials:

Field	Value
Username	`admin`
Password	`admin`

The Osprey sign-in screen: username and password fields above a Sign In button

On first login, you must change the default password before continuing. Enter admin as the current password and choose a new one. The default policy requires at least 8 characters, an uppercase letter, a number, and a special character.

A yellow banner also appears while you use the default admin username. Its Change Password form lets you change the password again. Dismissing the banner hides it for the current session. Administrators can also manage passwords under Admin > Users & Security > Users.

Account Security panel

Click the shield icon in the top-right header to open Account Security. It shows who you are signed in as (role and sign-in method) and offers two self-service actions for local accounts:

Change password — enter your current password and a new one. The security policy (minimum length, character requirements) is enforced server-side. After a successful change, every other session is signed out; the session you changed it from stays signed in. Accounts that sign in through SSO or LDAP change their password at the identity provider instead.
Two-factor authentication — see below.

Two-Factor Authentication (TOTP)

Password-based sign-in can use a time-based one-time code (TOTP) as a second factor. In the Account Security panel (shield icon), click Enable: scan the QR code with an authenticator app (or type the key manually), enter the 6-digit code to confirm, and save the recovery codes shown once — each works a single time if you lose your device. At the next sign-in, after your password you'll be asked for the code (or a recovery code).

MFA can be made mandatory for chosen roles in Admin > System Settings > Authentication (auth.mfa.required_roles); users in those roles are prompted to enroll.
Admins can clear a user's second factor (lost device) with Reset MFA in User Management; the user re-enrolls at next sign-in.
Single sign-on accounts do their second factor at the identity provider, not in Osprey.

Your First Working Topology

Use this route after installing Osprey and changing the initial password. Creating a network and adding recorders requires an administrator or engineer account.

Create a network and protocol instance. For example, create a network called Production and an instance for your existing OSPF process.
Choose a discovery method. Use SNMP if the router exposes the required database through SNMP, or GRE if you can configure a monitoring adjacency. Follow that method's setup instructions and router example.
Open the area's recorder card and check its status. Confirm that data is arriving and that the recorder covers the intended area. A green process indicator alone is not enough.
Select the area in the sidebar. Locate a known router and one of its expected neighbors. Click them to inspect their identities and links.
Enable SNMP traffic monitoring if you also want interface rates and utilization. This is separate from receiving the topology.
Open a link's traffic graph. Check its latest sample and direction. Allow a polling interval for new counters to arrive.

You should now have a topology you can compare with your routers, plus traffic measurements where SNMP access is available. Continue with common tasks, or use No Topology Data if the first area stays empty.

Mobile and Touch

On phones and small tablets, open the main menu with the hamburger button. The sidebar slides in from the left; tap outside it or press Escape to close it. Panels fill the screen. Minimize them to the bar at the bottom to switch between panels.

On the topology canvas, drag to pan and pinch to zoom. Tap a device or link for details. Long-press or tap with two fingers to open its context menu. Time Travel and Simulation also support touch; drag their time slider to move through history. Wide tables scroll sideways.

The mobile layout applies below 1024 pixels wide. The terminal and administrative forms work on a phone, but are easier to use on a larger screen.

The Help menu provides:

User Guide: Opens this user guide in a new tab.
Keyboard Shortcuts: Opens the shortcut reference (also accessible via ?).
About Osprey: Shows version and build information.

Understanding the Hierarchy

Osprey organizes network data in a hierarchy:

Network → Autonomous System → Routing Domain → Protocol Instance → Area → Devices/Links

Network: Top-level organizational boundary (e.g., "Production", "Lab").
Autonomous System: BGP AS number (auto-created, hidden in the UI).
Routing Domain: Global routing table, VRF, or L3VPN (a "default" domain is auto-created with each network).
Protocol Instance: A routing process. For OSPF: router ospf 1 (shown as "OSPF 1" or "OSPFv3 1 (v6)"). For IS-IS: router isis CORE (shown as "IS-IS CORE"). Supports OSPFv2, OSPFv3 (with IPv6 or IPv4 address family), IS-IS (ISO 10589), EIGRP, and BGP.
Area: An OSPF area (e.g., 0.0.0.0 for the backbone) or an IS-IS level (Level 1 or Level 2).

In practice, the Autonomous System and default Routing Domain are created automatically when you add a network. The sidebar hides the AS level entirely, so the typical workflow is:

Create a Network (e.g., "Production") -- this auto-creates a default AS (65000) and a default Routing Domain ("default", type global) behind the scenes.
Add a Protocol Instance under the network (e.g., OSPF process 1 or IS-IS instance "CORE").
Add an Area (OSPF area or IS-IS level) with a recorder to start discovering topology (see Section 3).

The sidebar shows the result: a network, the protocol instances underneath it, and each instance's areas with a badge per discovery method.

Hierarchy sidebar: a network containing an OSPF and an OSPFv3 instance, each listing its areas with GRE and SNMP badges

You only need to create additional Routing Domains manually if you have VRFs or L3VPNs. Use the + icon on a network and select "Add Routing Domain" for this.

Tip: Admin and engineer users see small action icons (add, edit, delete) when hovering over hierarchy items in the sidebar. Operator-role users can browse the hierarchy and view topology but cannot modify it.

Glossary

Term	Meaning in Osprey
Recorder	A configured source that collects topology or routing information. For example, a GRE recorder receives an area's link-state data. Some status labels and service names use collector for the same role.
SNMP target	A device configured for SNMP polling, including interface counters and device details. A topology recorder and an SNMP target can contact the same router for different purposes.
Enrichment	Information added to the discovered topology, such as hardware details, interface counters, or LLDP/CDP neighbors. Configure it per network.
Scope	The network, areas, devices, or protocols selected for a view or operation. A report may also have its own scope selector.
Coverage	The part of the network or time range for which usable observations are available. A running source does not guarantee complete coverage.
Freshness	How recently the source observed or verified the information. Check the timestamp and any stale-data label.
Routing domain	A separate routing table context, such as the global table or a VRF. The same prefix can exist in different domains.
Protocol instance	A particular routing process, such as OSPF process 1 or an IS-IS process named CORE.
Area / level	The routing scope below an instance: an OSPF area or the relevant IS-IS area/level.
Seed	An initial router address used to start discovery. It does not necessarily identify every router that will be polled.
LSDB	Link-state database: the routing protocol's descriptions of routers, links, and advertised prefixes.
BMP target	A configured router exporter from which Osprey accepts BGP Monitoring Protocol data. Its export and history settings determine what BGP information is available.
BGP-LS	BGP Link-State: router-exported topology information. It carries nodes, links, and prefixes rather than original LSA/LSP headers.
Snapshot	Recorded state at a point in time. Topology snapshots and routing history have their own coverage and retention.
Mutation / scenario	A mutation is one simulated change, such as failing a link. A scenario is a saved set of those changes. Neither applies router configuration.
SRLG	Shared Risk Link Group: links exposed to the same failure, such as circuits sharing one duct.
Overlay	Additional information drawn on the map, such as VPN membership or tunnel endpoints. Its meaning depends on the selected feature.

Understanding Data Quality

Before interpreting a map, report, or path, check what is selected, where its data came from, and when it was observed. A working recorder can still cover only part of your network.

Scope and Sources

The checked areas in the sidebar determine the visible topology. Some panels also have their own network, AS, protocol, or address-family selector. Check both selections when two views seem to disagree.

Source	What it contributes	What else you may need
GRE recorder	OSPF or IS-IS link-state data received through an adjacency	SNMP for interface counters and device details
SNMP recorder	Routing information exposed by the router's MIBs	Additional router access where the MIB or selected seed gives only partial coverage
BGP-LS source	Router-exported nodes, links, and prefixes	GRE for original LSA/LSP headers; SNMP for traffic counters
BMP target	BGP peers and routes exported by the monitored sessions	A history mode that records the detail you want to replay
SNMP enrichment	Interface rates, hardware details, LLDP/CDP neighbors, and supported service information	The relevant per-network discovery settings and router MIB support

Device details label the source as LSDB read, MIB reported, or Router exported. These labels explain how the information was obtained. See the glossary for the terms used throughout the guide.

Freshness and Missing Values

What you see	How to read it	What to check next
Recorder running	Its process is active	Last received data and area verification on the recorder card
Stale, partial, or incomplete	Some information is old or missing	The panel's source, timestamp, and stated reason
A blank rate or unavailable utilization	No usable measurement is shown	SNMP target, sample time, interface mapping, and live/historical mode
A measured rate of zero	The displayed sample records no traffic for that interval	Whether that interval and direction match your question
An empty report	No rows are available for the current selection and filters	Scope, filters, source support, and collection status
An unchanged topology	No change is visible	Recorder freshness; a stable network does not need to change to remain healthy

A missing value is not evidence of a healthy or idle network. Conversely, missing coverage does not prove a network fault. Follow the reason shown by the panel before changing router configuration.

Paths, Overlays, and History

A path can be calculated from topology or assembled from recorded routing decisions. Read its explanation and any incomplete segments before using it to assess reachability. Path interpretation describes the differences. A service overlay shows VPN membership or tunnel endpoints; it does not necessarily trace the links carrying packets.

In Time Travel, check the selected time and the coverage notes in the panel. Topology, traffic, BGP, and EIGRP history are recorded separately. One can be available while another is missing. Simulation results describe the model at the selected time; they are not measurements of a change applied to routers.

Common Tasks

These procedures connect the panels used for everyday investigation and maintenance. Check the scope, source, and freshness of the data before drawing a conclusion.

Investigating an Outage

Open Alerts > Active Alerts and note the affected device or link and the event time. If you acknowledge an alert, that records attention; it does not repair the fault.
Find the related incident in the dashboard or Activity Tray. Expand it to see the grouped symptoms and proposed root cause.
Open the affected device or link. Compare neighbor states, protocol states, and traffic. Check whether the source itself has lost contact.
Use Time Travel to compare the topology before and after the event. Confirm historical coverage for the devices involved.
Use Topology Diff to list changes, and inspect a path between affected endpoints. Read any missing-data explanation before concluding that traffic was unreachable.
Export the relevant report or topology for your incident record. Click Go Live when finished and check the current state.

Incident correlation is a starting point for investigation. A monitoring outage can remove visibility without proving a device or circuit failed.

Preparing Network Maintenance

Administrators and engineers can manage maintenance windows. Simulation itself evaluates the discovered model and does not apply router changes.

Select the affected areas and confirm that the devices, links, and traffic samples are current.
Open Tools > Simulation and check the protocol instance selector.
Add the planned link, node, or peer failures. For a shared failure such as several circuits in one duct, use an SRLG containing those links.
Inspect Impact for isolated devices and estimated utilization. Read the traffic estimate's available data and limitations.
Inspect Paths for changed or broken routes. Check important source/destination pairs as well as the summary.
Save the changes in Scenarios so the same case can be reviewed again. A saved scenario stores the simulated changes; later results depend on the topology used when it is loaded.
If appropriate, create a maintenance window with the intended scope and times. This suppresses matching alerts; it does not perform the maintenance.
Return to live mode before checking the actual change. Compare the observed result with the simulation and investigate any differences.

Explaining a Route Change

For BGP, this workflow requires recorded history covering the time and prefix in question. Enabling history now does not reconstruct earlier changes.

Open Reports > Routing > BGP Routes. Select the relevant AS and routing domain, then find the prefix.
Check the selected route's peer, next hop, and AS path. Use Route Explanation when investigating how the route contributes to an end-to-end path.
Open the row's ↺ replay action to view BGP Change Replay.
Step through the events around the reported change. Compare the old and new next hop and AS path, and look for a peer-state change or withdrawal.
Use Compare to compare two times. If the target recorded full history, inspect Candidate paths to see the alternatives that were recorded.
Check other affected prefixes in BGP AS Flow when you need the broader AS view.

For OSPF, IS-IS, or EIGRP, start with the device's routing table and path explanation, then compare the available history in Time Travel. The available detail depends on the protocol and recording method.

2. Dashboard

When you first log in (or when no hierarchy item is selected in the sidebar), you see the Dashboard -- a six-card overview of your entire network. The dashboard is the default landing page.

The dashboard's six cards: Network Health, Active Alerts, Recent Events, Active Incidents, Network at a Glance and Top Utilized Links

Network Health

Shows system status and counts of key resources.

Status indicator: A colored dot and label showing one of:
- Healthy (green) -- all infrastructure (DB, NATS) is reachable, the engine is running, all enabled recorders are running, and no areas are stale.
- Degraded (yellow) -- infrastructure is up but the engine is unresponsive, some recorders have issues, some SNMP targets are failing, or one or more areas are stale (not receiving updates).
- Unhealthy (red) -- the API, database, or NATS is unreachable.
- Checking (gray, pulsing) -- initial health check in progress.
Counters: Networks, Areas, Devices, Links, Collectors (running/total), and SNMP Targets (active/total).

Click the status indicator in the bottom bar to open the System Health popover, which shows the status of all 7 services:

Service	What it checks
API Server	Whether the health endpoint itself is reachable
Engine	NATS heartbeat (published every 15s) — shows freshness like "Healthy · 12s ago"
Collector Manager	NATS heartbeat — shows freshness
SNMP Poller	NATS heartbeat — combined with SNMP target count
Database	PostgreSQL ping with latency
Message Bus	NATS connection status
Live Updates	WebSocket connection to the API

Heartbeat-based services (Engine, Collector Manager, SNMP Poller) show three states:

Healthy (green) -- last heartbeat received within 45 seconds
No heartbeat (yellow, pulsing) -- last heartbeat 45–120 seconds ago
Down / Not responding (red, pulsing) -- no heartbeat received for over 120 seconds, or never seen

Active Alerts

Displays severity badges (critical, warning, info) and lists the top 5 firing alerts with colored severity dots. If there are no active alerts, the card shows "No active alerts."

Recent Events

A 24-bar sparkline histogram shows event frequency over the last 24 hours (one bar per hour). Below it, the 8 most recent topology events are listed with color-coded type badges (green for additions, red for removals, amber for changes) and relative timestamps (e.g., "5m ago", "2h ago").

Active Incidents

Shows the total correlated incident count with severity badges and summaries of the top 3 active incidents. Each incident displays its event count and time since last event. Incidents group related events (e.g., multiple link failures caused by a single device going down).

Network at a Glance

A clickable list of all networks with per-network statistics (areas, devices, links). Clicking a network loads its full topology on the canvas and opens the sidebar for navigation.

Tip: This is the fastest way to jump into a specific network's topology from the dashboard.

3. Setting Up Topology Discovery

Choose a discovery method based on the access your routers provide:

Method	Router setup	What Osprey receives	Update timing
GRE recorder	Configure a GRE tunnel and an OSPF or IS-IS adjacency	Link-state database, including protocol headers	As the router floods changes
SNMP recorder	Enable SNMP and allow access from Osprey	OSPF or IS-IS database contents exposed by the router's MIB	At the recorder's poll interval
BGP-LS source	Export link-state data through BMP or a direct BGP peering	Router-exported nodes, links, and prefixes	As the router exports changes

GRE and SNMP can cover the same area. BGP-LS can supply topology where neither is available; see BGP-LS setup for source selection and limits. Available detail depends on what the router exposes.

EIGRP uses SNMP to read each router's neighbors and forwarding information. It has no shared link-state database. BGP routes and history use BMP. Layer 2 neighbors use LLDP/CDP through SNMP. Their setup is described below.

An EIGRP path can contain a known candidate that the router is not known to use. Osprey warns when the stored routing-table evidence does not confirm a followed next hop. If that uncertainty affects the chosen network exit, its domain and the following domains show inferred with an explanation. The route drawing remains available, but it is not a confirmed forwarding path. Reaching an attached network in the model does not prove packet delivery.

For supported IPv6 EIGRP routers, a full route refresh also records which next hops the router installed. Osprey uses those neighbors when the previously recorded candidate was not installed. Older history and routers that do not provide sufficient information keep the uncertainty warning. A failed refresh may leave an older observation available; it is not proof of current forwarding.

The LSDB Browser shows live LSA header fields only where a GRE recorder received them. SNMP can supply the database contents, but Osprey does not display polled header values as live data. BGP-LS does not carry LSA/LSP headers. With partial GRE coverage, the browser shows how many displayed LSAs have headers.

Creating the Hierarchy

Before adding recorders, create the network hierarchy in the sidebar.

Step 1 -- Create a Network:

Open the sidebar by clicking the toggle tab on the left edge of the screen (or via View > Sidebar).
Click the + icon next to the "Networks" heading at the top.
Enter a name (e.g., "Production") and an optional description.
Click Create.

This automatically creates a hidden Autonomous System (ASN 65000) and a default Routing Domain ("default", type global) behind the scenes. You do not need to create these manually.

Step 2 -- Add a Protocol Instance:

Hover over the network name in the sidebar and click the + icon that appears.
Select Add Protocol Instance.
Choose the protocol (OSPFv2, OSPFv3, IS-IS, EIGRP, or BGP) and enter an identifier:
- OSPF: Enter a process ID (e.g., 1 for router ospf 1). When OSPFv3 is selected, an address family selector appears (IPv6 default, IPv4 for RFC 5838 AF extensions).
- IS-IS: Enter an instance tag (e.g., CORE for router isis CORE). Shown in the sidebar as "IS-IS CORE".
- EIGRP: Enter the EIGRP AS number and select IPv4 or IPv6 for the initial instance. The recorder discovers both families; see EIGRP recording.
- BGP: Enter the local ASN (e.g., 65000). Only one BGP protocol instance is allowed per routing domain. BGP instances do not have areas -- instead, you add BMP targets under them (see Setting Up BGP Monitoring).
- Optionally add a description.
Click Create.

Step 3 -- Add an Area with a Collector:

Areas (OSPF areas or IS-IS levels) are created together with their first recorder through the Tunnel Quick-Add dialog. Hover over the Protocol Instance, click +, and select Add Area. This opens a dialog where you can specify the area ID (or IS-IS level), area type, and recorder configuration all at once. See Method 1 or Method 2 below.

Alternatively, if you need additional routing domains (for VRFs or L3VPNs), hover over the network, click +, and select Add Routing Domain.

Tip: You can also add recorders to existing areas. Hover over an area in the sidebar, click the + icon, and choose Add Recorder (for GRE) or Add Recorder (SNMP). An area can have both a GRE recorder and an SNMP recorder simultaneously.

Editing or Deleting the Hierarchy

Admins and engineers can edit or delete hierarchy entries using the buttons that appear when hovering over a sidebar row. Use Edit to change an existing entry; deleting and recreating it is not a rename.

Deletion permanently removes the selected entry and its children. Read the confirmation carefully, especially when deleting a network or protocol instance. If a recorder assigned elsewhere still discovers this scope, disable or rescope that recorder first; Osprey refuses the deletion while that conflict remains.

Where offered, Also delete topology history removes the associated historical data too. Leave it unchecked to retain history, but do not expect discovery to reconnect it later: rediscovered entries receive new identities, and old identity-bound history and alert scopes are not automatically reattached. Retained history for deleted areas can be purged later through the administrator API, not from a recreated sidebar entry.

Method 1: GRE Tunnel Discovery

GRE tunnels form a real IGP adjacency with your network. Osprey receives the full link-state database and tracks changes in real time. OSPFv2, OSPFv3, and IS-IS are all supported -- the Tunnel Quick-Add dialog adapts based on the parent protocol instance.

Open the Tunnel Quick-Add dialog by either:
- Hovering over a Protocol Instance in the sidebar, clicking +, and selecting Add Area (creates both the area and the recorder).
- Hovering over an existing Area in the sidebar, clicking +, and selecting Add Recorder (adds a GRE recorder to an existing area).
Select GRE as the discovery mode (this is the default).
Fill in the required fields:
- GRE Remote: The router address used as the GRE tunnel endpoint. It must be reachable from Osprey.
- GRE Local: The IP on your Osprey server that faces the remote router.
- Tunnel IP: The /30 or /31 point-to-point address for the tunnel interface (e.g., 10.254.0.1/30 for OSPFv2, or fe80::1/64 for OSPFv3). For IS-IS this field is called Local Address (CIDR) and lives in the IS-IS Configuration section; the peer address is derived from the subnet.
- Tunnel Peer: The remote end's tunnel IP (e.g., 10.254.0.2). Not asked for IS-IS (derived).
Optionally expand the Advanced section to configure:
- Router ID: Osprey's OSPF router ID. Router IDs are always 32-bit dotted-decimal, even for OSPFv3. For OSPFv2 it defaults to the tunnel-local IP when left blank; for OSPFv3 there is no IPv4 address to derive it from, so the field is required (it appears in the P2P Addressing section, not under Advanced). For IS-IS, this field is replaced by NET (Network Entity Title, e.g., 49.0001.0192.0168.0001.00).
- Hello/Dead intervals: Timer values (OSPF defaults: 10s hello, 40s dead; IS-IS defaults: 10s hello, 30s hold).
- Cost, Priority, MTU, TTL: Fine-tuning parameters. IS-IS uses wide metrics by default (range 1--16777215).
- Authentication: None, simple password, or MD5/SHA-HMAC with key ID. (OSPFv3 uses IPsec for authentication external to the protocol, so in-protocol authentication is hidden for v3 recorders. IS-IS supports HMAC-MD5 (RFC 5304) and HMAC-SHA-256 (RFC 5310, with key ID), configured directly in the IS-IS Configuration section; the recorder signs its Hellos, SNPs, and its own LSP, and logs — but never drops — incoming PDUs that fail verification.)
If creating a new area:
- OSPF: Enter the Area ID (e.g., 0.0.0.0 for backbone; you can also use integer notation like 0 which auto-converts to dotted-decimal) and Area Type (normal, stub, or NSSA). The recorder uses this type for its OSPF Hello option bits — stub/NSSA neighbors reject Hellos with mismatched options (RFC 2328) — and a recorder added to an existing area inherits that area's type automatically.
- IS-IS: Select the Level (Level 1, Level 2, or Level 1/2) from the dropdown.
Click Create. The collector-manager detects the new config within 10 seconds, creates the GRE tunnel, and starts adjacency formation.

An IS-IS GRE recorder waits for the initial link-state database exchange before publishing topology. An Up adjacency alone does not mean that exchange has finished. After a restart, partial incoming data does not create a series of apparent removals. If the exchange remains incomplete, topology freshness does not advance; check the recorder logs for the initial database synchronization completion message.

Requirements: The Osprey server needs IP connectivity to the remote router. The collector-manager runs as root (GRE tunnels require NET_ADMIN and NET_RAW capabilities).

On the router side, configure a GRE tunnel back to Osprey and add it to the IGP. The Cisco IOS examples below include the MTU explicitly. The OSPF examples assume a 1500-byte underlay without extra encapsulation such as IPsec. If your path needs a smaller MTU, set the same lower value on the router and in Osprey's recorder form.

Example (Cisco IOS, OSPFv2):

interface Tunnel100
 ip address 10.254.0.2 255.255.255.252
 ip mtu 1476
 ip ospf 1 area 0
 ip ospf cost 1000
 ip ospf priority 0
 tunnel source <router-wan-ip>
 tunnel destination <osprey-server-ip>
 tunnel mode gre ip

In the Tunnel Quick-Add form, set Tunnel IP = 10.254.0.1/30, Tunnel Peer = 10.254.0.2, and MTU = 1476 under Advanced.

Example (Cisco IOS, OSPFv3 over IPv4 GRE):

interface Tunnel100
 ipv6 enable
 ipv6 address fe80::2 link-local
 ipv6 mtu 1476
 ospfv3 1 ipv6 area 0
 ospfv3 cost 1000
 tunnel source <router-wan-ip>
 tunnel destination <osprey-server-ip>
 tunnel mode gre ip

For OSPFv3, the outer GRE tunnel can use IPv4 or IPv6. Enter GRE Remote and GRE Local addresses from the same family. On Cisco IOS, use tunnel mode gre ip for IPv4 or tunnel mode gre ipv6 for IPv6.

The addresses inside the tunnel remain IPv6: set Tunnel IP to fe80::1/64 and Tunnel Peer to fe80::2. Also enter a 32-bit Router ID, such as 10.254.0.1. For the IPv4 GRE example, use MTU = 1476 in Osprey.

Example (Cisco IOS, OSPFv3 over IPv6 GRE):

interface Tunnel100
 ipv6 enable
 ipv6 address fe80::2 link-local
 ipv6 mtu 1448
 ospfv3 1 ipv6 area 0
 ospfv3 cost 1000
 tunnel source <router-ipv6-address>
 tunnel destination <osprey-server-ipv6-address>
 tunnel mode gre ipv6

For this example, enter IPv6 GRE Remote and GRE Local addresses in Osprey and use MTU = 1448. Keep the same inner tunnel addresses and Router ID as above. The smaller MTU accounts for the IPv6 outer header and Linux's encapsulation-limit option.

A router can host an OSPFv2 recorder over IPv4 GRE and an OSPFv3 recorder over IPv6 GRE without an endpoint collision. OSPFv2 and IS-IS recorders use IPv4 GRE.

Example (Cisco IOS, IS-IS over IPv4 GRE, Ethernet MTU 1500):

The following example is based on a working Cisco IOS recorder connection. It uses a 1500-byte Ethernet underlay and an effective tunnel MTU of 1476 bytes. Addresses and the IS-IS process name have been replaced with example values. The existing IS-IS process uses wide metrics.

interface Tunnel100
 ip address 10.254.0.2 255.255.255.252
 ip mtu 1476
 ip router isis CORE
 isis circuit-type level-2-only
 isis metric 16777214
 tunnel source <router-wan-ip>
 tunnel destination <osprey-server-ip>
 tunnel mode gre ip

IS-IS MTU: The verified IOS configuration uses ip mtu 1476 and has no explicit clns mtu or process-level lsp-mtu override. show clns interface reports an effective CLNS MTU of 1476, and the recorder adjacency is Up.

Check your router with show clns interface Tunnel100 and show clns neighbors. Use the reported CLNS MTU to assess IS-IS; the IP MTU alone is not sufficient across platforms. The 1476-byte tunnel payload plus 20 bytes IPv4 and 4 bytes GRE fits the 1500-byte underlay. Larger IS-IS packets can require outer IPv4 fragmentation, which Osprey supports receiving and reassembling. Any firewall on that path must allow those fragments through.

If another router platform rejects the adjacency because its LSP size exceeds the tunnel MTU, check that platform's requirements before changing lsp-mtu. That setting affects the routing process, and changing only the tunnel router does not reduce LSPs generated elsewhere. See Cisco's CLNS and LSP MTU reference. Osprey's IS-IS form has no MTU field; Advanced > MTU belongs to OSPF recorders.

The verified example uses no authentication. If the network requires MD5, add these interface commands and configure the same key in Osprey:

 isis authentication mode md5
 isis authentication key-chain OSPREY-ISIS

Define key chain OSPREY-ISIS, key 1, and key-string <key> globally on the router.

Check OSPF MTU: Use show ip interface Tunnel100 for OSPFv2 or show ipv6 interface Tunnel100 for OSPFv3. Compare the reported IP MTU with the recorder's Advanced > MTU value. A mismatch can leave the adjacency stuck in ExStart.

Timers and authentication: Match OSPF hello/dead timers at both ends; Osprey defaults to 10/40 seconds. IS-IS defaults to a 10-second hello and 30-second hold time. Match the configured authentication mode and key on the router and recorder. Use a high IS-IS metric for the monitoring tunnel; the verified example uses 16777214.

Method 2: SNMP Discovery

SNMP discovery polls routers via SNMPv2c or v3 to walk the link-state database MIB. No tunnel configuration needed on the router -- just ensure SNMP is enabled and reachable from the Osprey server. Supported MIBs: OSPFv2 (RFC 1850), OSPFv3 (RFC 5643), and ISIS-MIB (RFC 4444). For IS-IS, Osprey auto-detects Cisco proprietary ISIS-MIB OIDs and falls back to them when the standard MIB is unavailable.

Osprey polls each discovered router at a reachable management address (a probe-confirmed loopback), not at its OSPF router-id — so discovery and the multi-area crawl also work on fabrics whose management plane is IPv6-only, where the IPv4-looking router-id is not routable. When OSPFv2 and OSPFv3 both run on a dual-stack network, you can point an OSPFv2 and an OSPFv3 recorder at the same seed address; they are tracked as distinct recorders and each reuses whichever address family is actually reachable.

For EIGRP, follow EIGRP recording below. The following steps configure OSPF or IS-IS discovery.

Open the Tunnel Quick-Add dialog by either:
- Hovering over a Protocol Instance in the sidebar, clicking +, and selecting Add Area.
- Hovering over an existing Area, clicking +, and selecting Add Recorder (SNMP) (pre-selects SNMP mode).
Select SNMP as the discovery mode.
Enter the Target IP (the router's management IP address).
Select a Credential Profile (the dropdown appears when profiles exist; the profile dictates both the SNMP version and the credentials), or pick the SNMP version and enter inline credentials:
- v2c: Community string (e.g., public)
- v3: Username, auth protocol (MD5/SHA), auth password, privacy protocol (DES/AES), privacy password
Optionally configure:
- Poll Interval: How often to poll (in seconds).
- Crawl ABRs/L1L2: Follow IGP neighbors to discover additional areas and build the full topology from a single seed device. An OSPF crawl creates a scoped child for each discovered area and then turns the parent into a single-area recorder. For IS-IS, a new multi-level crawl hands off to strict per-area recorders by default through the bootstrap lifecycle below.
- Bootstrap strict per-area recorders (IS-IS only, shown after enabling multi-level crawl; checked by default for a new recorder): persistently opts this parent into the controlled handoff described below. Clear it to keep a permanent multi-level crawler. The server-side switch must also be enabled, as it is in the shipped configuration. Editing an existing recorder never checks this option for you.
If creating a new area, enter the area ID. (No area type is asked here — SNMP discovery forms no adjacency, so the area type does not affect it.)
Click Create.

For an IS-IS recorder with Crawl ABRs/L1L2 disabled, the selected area is a hard boundary. A Level 2 recorder reads and publishes only the shared Level 2 database. A Level 1 recorder reads only Level 1 and verifies that the router's advertised area address matches the selected area exactly; a mismatch leaves the last complete topology in place and marks the recorder source degraded. A crawler remains the explicit multi-area mode.

IS-IS bootstrap to strict per-area recorders

IS-IS bootstrap replaces one multi-level SNMP crawler with a separate recorder for each Level 1 area. The original recorder continues as the Level 2 source. This makes each area's polling and health visible independently.

The original recorder is called the parent. The Level 1 recorders it creates are its children. A strict recorder reads only its assigned area or level. GRE and BGP-LS sources remain separate and do not satisfy the bootstrap's requirement for a working SNMP child.

Bootstrap requires both controls. For a new multi-level IS-IS recorder both are on by default, matching the OSPF crawl:

The global snmp.isis_bootstrap_enabled switch in /etc/osprey/osprey.yaml is true in the shipped configuration. It is read once at process start. Set it to false and restart osprey-collector-manager to stop all new provisioning and handoffs (kill switch); a missing key also leaves it off.
Bootstrap strict per-area recorders on the parent is checked by default when you create a Level 2 SNMP recorder with Crawl multi-level, and API clients get the same default unless they send snmp.bootstrap_recorders: false. To convert an existing crawler, edit it and check the option. Existing recorders without this opt-in never change behavior during an upgrade.

The parent card shows progress:

Phase	Meaning
Discovering areas	Finding the Level 1 areas and a reachable SNMP target for each. Areas without a usable target remain listed as blockers.
Provisioning recorders	Reusing a matching strict recorder or creating a child with the parent's credentials.
Awaiting snapshots	Waiting for each child's complete area snapshot to be stored. The card shows completed/expected counts and the areas still waiting. The parent continues its multi-level crawl.
Complete	Every required snapshot is stored. The parent becomes Level 2-only and the children become available for normal management. The handoff is recorded in the audit log.

Before handoff, child cards show Managed. Their configuration is read-only while the parent controls setup. Diagnostics identifies the owner as IS-IS bootstrap (read-only).

After handoff, the badge changes to Auto-created and normal edit, pause, and delete controls appear. You can change the target, credentials, polling interval, and description. The recorder's generated name, assigned area, protocol placement, strict scope, and creation history remain fixed.

A recorder's tunnel link reflects its observed status. When all observations are Down, the graph shows Down; a retained recorder object does not prove an active connection. Duplicate observations use an observed Up link if available. Withdrawn objects remain subject to the normal retention policy.

Each SNMP-LSDB recorder card presents process state and effective freshness on one line, then area verification independently on the next line:

Verified -- the source most recently supplied a complete baseline, or a stable SPF check proved that baseline still current.
Pending -- a new or changed source has not supplied a complete baseline yet.
Unreachable -- the source cannot currently be polled.
Incomplete LSDB -- a walk ended but failed the summary/TLV integrity checks. The partial result is rejected and cannot remove topology.

The verification line uses human labels such as Complete snapshot and SPF unchanged. Its count is protocol-specific: OSPF reports LSAs, while IS-IS reports LSPs; those figures are not directly comparable. The compact card also combines SNMP version, poll cadence, and evidence. Expand Diagnostics for the generated recorder name, separate data and verification timestamps, the stable backend reason code, and protocol details. When there is only one diagnostic line, it is shown directly without an expander. A verified recorder's freshness uses its latest successful data update or verification. An unchanged topology can therefore remain fresh. Pending, Unreachable, or Incomplete LSDB takes precedence over the freshness timestamp.

Prometheus exposes the same facts on the collector-manager endpoint (port 9091): osprey_snmp_isis_area_verification is a one-hot current verdict per recorder and area, and osprey_snmp_isis_bootstrap_areas reports the active parent's desired and acknowledged counts. The latter returns to zero after handoff; durable completion remains on the parent card and in the audit log.

If a source becomes unreachable or returns an incomplete database, Osprey keeps its last complete topology while the enabled recorder continues to retain it. Last verified stops advancing. Retained data is available for inspection, but does not mean the source is healthy.

An enabled recorder also continues to take precedence over BGP-LS during a polling failure. To use a covering BGP-LS source, restore polling or deliberately disable the recorder after handoff. Osprey does not switch sources automatically when verification fails.

To cancel before handoff, clear the parent's bootstrap checkbox, or turn off the global switch and restart osprey-collector-manager. The parent remains broad. Children already created remain enabled and read-only for inspection; no topology, history, or layout is deleted.

To roll back after handoff on the same binary:

Turn off the global switch and restart osprey-collector-manager so another handoff cannot race the rollback.
Edit the original parent and enable multi-level crawl again. Record the UTC start time.
Wait for one complete parent crawl and verify fresh parent snapshot coverage for every expected Level 1 area and Level 2. Do not infer this from a green process dot; verify the area coverage timestamps are later than the rollback start.
Disable the Auto-created L1 recorders through their normal pause controls. Leave the hierarchy and topology tables untouched.
Confirm every L1 child is stopped and the broad parent remains verified across all scopes.

The manager stops the children within its normal update interval. Keep them if the rollback may be temporary, so their configuration and creation history remain available. The parent keeps its bootstrap opt-in. To keep it broad permanently, also clear its bootstrap checkbox; otherwise the next manager start with the switch on begins a new generation.

To return to per-area recorders, re-enable the Auto-created L1 recorders first, then turn the global switch back on and restart osprey-collector-manager. The new generation adopts the existing recorders without changing them. A disabled auto-created recorder is never re-enabled for you: it blocks the handoff until you enable, repair, or delete it. An unchanged recorder acknowledges with its next full snapshot, which it publishes at least hourly, so this handoff can take up to about an hour. Until then the parent keeps publishing every area, and each Level 1 area has two SNMP sources.

Never downgrade to a binary from before strict IS-IS scoping while L1 children are enabled. An old L1L2 child can publish Level 2 again and create duplicate ownership. The same rollback sequence is a hard downgrade precondition: broad parent healthy first, L1 children disabled second, package downgrade last. Take a database backup and retain the original encryption key before any rollback or downgrade.

Tip: Credential Profiles let you save named SNMP credential templates for reuse across multiple recorders and SNMP targets. Create them under Admin > Monitoring > Credential Profiles.

EIGRP recording

EIGRP discovery uses read-only SNMP access to Cisco's CISCO-EIGRP-MIB. Osprey does not form an EIGRP adjacency.

Create or edit a recorder:

Choose EIGRP in the recorder form.
Under Recording, select one EIGRP AS or All EIGRP ASes, and enter seed device addresses, one per line.
Under SNMP access, select a credential profile or enter credentials.
Under Route history, review the route-table walk interval. A new recorder starts at the recommended 60 minutes. Clear the field if it should inherit the network's discovery interval instead.
Save the recorder. It records both IPv4 and IPv6, creating a separate protocol instance for each discovered AS and address family.

Seeds and recording scope. Seeds help Osprey discover the first devices. Recording then covers eligible devices throughout the recorder's network, including devices outside the seed list. All EIGRP ASes also applies throughout that network. Deleting a device removes its seed address, although a live device can still be discovered again through LLDP/CDP.

Route history interval. Sixty minutes is the default for a new recorder and provides two hours and ten minutes of historical coverage after a successful complete walk. A shorter interval records changes sooner and increases SNMP load. The minimum is five minutes. Clearing the field preserves the older inheritance behaviour and uses the network's discovery interval, which is often six hours. The form always shows the effective choice. Historical coverage lasts twice the interval plus ten minutes. Adjacency polling has its own faster schedule.

Changing the interval requests an immediate walk. Discover now also rereads the tables. Route recording continues when traffic-counter collection is switched off.

Use a field's help icon to read more about seeds, AS selection, or history coverage. Enter or Space opens help; Escape closes it while the button has focus. Input errors and empty-seed warnings stay visible without opening help.

Reading the result:

The sidebar uses Topology because EIGRP has no areas. Link details identify each instance by AS and family, such as AS 100 (v4).
The device's EIGRP tab lists neighbors, enabled interfaces, and reported timers. Known endpoints appear as links on the canvas. Links sharing an interface with another protocol can merge into one edge.
The routing table shows D for internal and D EX for external routes. The metric is the router's reported distance; administrative distances default to 90 and 170. Change the model's distances under Admin > System Settings > Routing.
EIGRP links have no individual SPF cost. Use the observed path view to follow the routers' recorded forwarding choices.

Recorder status. Manage the recorder from its owning card. A Shared recorder card points to the same recorder from another AS/family view; it does not represent a second process.

Last IPv4 observation or Last IPv6 observation reports the last poll that observed that card's AS and family. It does not confirm a complete route-table walk or coverage of every device. Route history has separate timestamps and coverage. An absent timestamp means freshness is unavailable.

BGP-LS Topology Export (two ways in)

BGP-LS lets a router export nodes, links, and prefixes from its IGP database. Use it when you can obtain a link-state export but cannot deploy a GRE or SNMP recorder. Osprey labels this data Router exported. BGP-LS does not include the original LSA/LSP headers.

Choose how to receive it:

Source	Setup in Osprey	Setup on the router
BMP	Enable Ingest BGP-LS from this target on a BMP target.	Mirror a BGP-LS session through BMP.
Direct BGP-LS peer	Use + on the BGP instance, or open Reports > Routing > BGP-LS..., then Sources, and add a peer.	Configure a neighbor for Osprey and enable link-state export for it.

For direct peering, Osprey initiates the connection to the router's TCP port 179. It does not listen for inbound BGP connections or advertise routes. Set the peer's AS, routing domain, addresses, hold time, and object budget in the form. A hold time of 0 disables keepalives. Engineers and administrators can manage peers.

Waiting for the initial database. Osprey waits until the initial export finishes before using the new topology. It keeps the previous view while the dump is arriving.

If the source sends End-of-RIB, Osprey records observed completion.
If the source omits it, Osprey can infer completion after a quiet interval. The source shows completion inferred from quiet. Objects absent from that dump are not deleted merely because they were missing.
Enable Require observed End-of-RIB on the source to wait for an actual marker. The previous view remains until one arrives.

Some exporters omit End-of-RIB. BMP Loc-RIB does not define such a completion marker. Inferred completion records that distinction; it does not by itself indicate lost data.

Incomplete or rejected input. Each source has an object budget (max_bgpls_nlri). Exceeding it makes Osprey refuse that source's scope rather than draw an incomplete topology. Lost batches, a full ingest queue, message-bus failures, and invalid advertisements can also cause a refusal. The BGP-LS panel identifies the source and reason. Affected projected areas can become empty.

Check the stated cause before reconnecting. Recovery needs a fresh session and a complete export within the budget; malformed advertisements also require correcting the exporter.

Using the topology:

Areas appear in the sidebar with a BGP-LS badge. The Sources tab identifies the feeding source.
Devices, links, and prefixes are available to the canvas, paths, simulation, and reports. Path explanations identify BGP-LS areas and reconstructed interface or designated-router identities.
The LSDB Browser is unavailable for BGP-LS-only areas because the export contains no LSA headers. Stub/NSSA area types must be declared in the area's settings; BGP-LS does not supply them.
Osprey selects management-address candidates for SNMP and DNS enrichment. The displayed source distinguishes an observed address from an unverified router-ID fallback.
Exported segment-routing details, including SRGB/SRLB, node MSD, and prefix/adjacency SIDs, populate the SR inventory when supplied.

Source precedence. An enabled GRE or SNMP recorder takes precedence in its area. Disable it to let BGP-LS supply that area; re-enable it to return to the recorder. A polling failure alone does not trigger this switch.

BGP-LS recorder rows are read-only and appear as BGP-LS · followed by the target or peer name. Change settings on the source itself. Deleting the source removes its projection and recorder row.

BGP-LS devices count toward the license node limit. A large export can exceed the 32-node evaluation allowance, which has no grace period and refuses the excess at discovery; see License for admission behavior.

Collector Status

Each area shows one aggregated status dot. Click its right-aligned acquisition-method label (GRE, SNMP, or BGP-LS) to open the management block and see every recorder:

Green (running): The recorder is running. Also check its data freshness and area verification.
Blue pulsing (discovering): SNMP recorder is actively crawling/discovering neighbors.
Yellow pulsing (starting): Initializing GRE tunnel or SNMP session.
Gray pulsing (pending): Configuration saved but not yet picked up by the collector-manager.
Gray solid (stopped): Disabled by user.
Red (error): Failed -- open the management block to see the recorder and full error.
Yellow (unreachable/incomplete): The process may still be running, but this area's source verification failed. The card distinguishes an unreachable source from an incomplete LSDB; its Diagnostics section preserves the stable backend reason code.

For operator-managed recorders, administrators and engineers use the actions in the expanded management block:

Edit (pencil icon): Modify the recorder configuration. Saving restarts the recorder with the new settings.
Toggle (pause/play icon): Enable or disable the recorder. The collector-manager handles start/stop within 10 seconds.
Delete (trash icon): Remove the recorder after confirmation.

Active, pre-handoff IS-IS bootstrap children show no actions. Completed Auto-created children are operator-managed and show the normal actions. A covering recorder homed in another area is informational/read-only here; manage it from its home area.

To retire an auto-created IS-IS Level 1 recorder, pause it and verify that it stops. A covering BGP-LS source can then take over. Pausing preserves the area, history, and layouts. Deleting a recorder removes its configuration; deleting the area is a separate action. Follow Stopping or Replacing a Recorder before removing a source.

Tip: When multiple recorders exist on the same area (for example GRE plus SNMP), the area dot summarizes them while the expanded block preserves each source's exact state and evidence.

Stopping or Replacing a Recorder

Use these steps for a recorder whose management actions are available. You need an administrator or engineer account. Check all sources covering the area before stopping one: another recorder may continue updating the same topology.

Expand the area's GRE, SNMP, or BGP-LS label and identify the source you intend to replace. A recorder shown as covering another area must be managed from its home area.
Note its protocol, area or level, endpoints, and credentials. Follow the relevant discovery procedure for the replacement. A replacement GRE recorder must have a valid tunnel endpoint combination; do not assume duplicate tunnels can run together.
When the two sources can coexist, verify the replacement's data before pausing the old recorder. Otherwise, plan for the collection gap during the switch.
Pause the old recorder and confirm its status becomes stopped. Check that the intended replacement supplies current data for the area.
Keep the paused configuration while validating the replacement. Delete it when it is no longer needed. Removing that configuration is separate from deleting the area or its topology.

Pausing a topology recorder does not pause SNMP enrichment and traffic polling. Pausing regular SNMP polling also does not stop every on-demand request. Historical data remains subject to its configured retention.

If a recorder has no management actions, check the IS-IS bootstrap ownership rules. If area deletion is blocked, follow the named source dependency instead of repeatedly trying to delete it.

Network Enrichment

Open Enrichment from a network's sidebar row to check its SNMP capabilities and coverage. Each card shows whether a capability is enabled and the health of its observations. Expand a card for its interval and settings; enabled does not necessarily mean that data has been received.

For SNMP discovery, click the uncovered-device count when offered to see which devices lack coverage. Check their targets and credentials before changing discovery settings. Run discovery now requests an immediate interface-discovery pass; it does not reset the network or create a GRE recorder.

Administrators can use the SNMP section's Enabled / Paused button to pause or resume polling for this network. Existing observations remain visible when polling is paused, so check their age before using them. Capability and credential changes also require an administrator.

See L2 configuration for neighbor discovery and MPLS discovery for service-specific requirements.

SNMP Settings (per network)

Open the network's Enrichment panel from the sidebar to configure SNMP and L2 discovery for that network:

Capability cards with per-capability toggles and intervals: interface discovery/enrichment, traffic counters, L2 enrichment (LLDP/CDP), and L2 switch crawling. Each card shows live health (last run, queue size, neighbor counts).
Pause polling: Pauses regular enrichment and counter collection for the network. On-demand boost and separate topology recorders can still run.
Credential profiles: primary and fallback profile selectors (fallback is tried automatically when primary credentials fail).
Advanced: PDU timeout, retries, auto-disable threshold, counter poll interval, L2 stale retention, include-routers-in-crawl, and L2 crawler operations (run a crawl cycle now, reset this network's crawler queue — admin only).

The LLDP/CDP and crawling ON/OFF toggles are also available inline in the network edit form in the sidebar. See Per-Network L2 Configuration.

SNMP Traffic Monitoring

Separately from topology discovery, Osprey polls device interfaces for traffic statistics (utilization, errors, discards). This is handled by the SNMP Poller service, which is independent of the topology recorders.

Set up SNMP targets under Admin > Monitoring > SNMP Targets:

Click Add Target.
Enter the device management IP and SNMP credentials (or select a credential profile).
The SNMP poller begins collecting interface counters at the configured interval (default 5 minutes). Open the network's Enrichment panel from its sidebar row, then use Advanced > Counter poll interval.

The SNMP Targets manager listing each polled device with its IP, SNMP version, interval, last poll and enable toggle

Targets that fail 10 consecutive polls are automatically disabled to prevent wasted resources. You can re-enable them manually after fixing the underlying issue.

Pausing the SNMP Poller: Use Stop/Start SNMP Poller in the SNMP Targets manager to pause regular discovery and counter polling across targets. On-demand traffic boost can still run, and topology SNMP recorders managed by the collector-manager are separate. The pause is therefore not a complete stop of all SNMP traffic. Click the button again to resume regular polling.

Traffic data enables:

Utilization coloring on the topology canvas (View > Color > By Utilization)
Link Detail Panel traffic charts (with automatic 10-second boost polling while the panel is open)
Congestion alerts, when configured using the 80% warning and 95% critical templates
Top Utilized Links card on the dashboard
Congestion Trend diagnostic report (Reports > Diagnostics > Congestion Trend)
MTU mismatch detection (Reports > Diagnostics > MTU Mismatch) — detects interface MTU mismatches across link endpoints via SNMP IF-MIB

L2 Neighbor Discovery (LLDP/CDP)

Osprey discovers Layer 2 adjacencies via SNMP walks of the LLDP-MIB (IEEE 802.1AB) and CDP-MIB tables. This runs automatically alongside IGP topology discovery (OSPF or IS-IS) when enabled.

How it works:

The SNMP poller walks LLDP-MIB on each target device. If LLDP data is unavailable (e.g., older IOS devices), it falls back to CDP-MIB per device.
Discovered L2 neighbors are stored with chassis ID, port ID, system name, management addresses, and platform description.
Osprey keeps neighbors that advertise bridge or router capability. Other endpoints are excluded.
Platform-based filtering automatically excludes wireless access points (Cisco AIR-/Aironet/C91xx, Aruba, Meraki, Ubiquiti, Ruckus) and Cisco UCS Fabric Interconnects (identified by "U: Uplink" / "S: Server" port descriptions) even when they advertise bridge capability.
Stale neighbors (not seen within the configured expiry window) are automatically cleaned up.

Configuration:

L2 discovery is configured per network in the network's Enrichment panel (and via the ON/OFF toggles in the network edit form -- see Per-Network L2 Configuration below):

Setting	Default	Description
L2 Discovery	on	Master toggle for LLDP/CDP neighbor discovery on monitored routers
Switch Crawling	off	Follow neighbor connections to discover switches via LLDP/CDP. Phones, APs, and endpoints are excluded.
Crawl Interval (hours)	6	How often the L2 crawler runs
Max Crawl Depth	3	Maximum number of neighbor hops from a router seed
Neighbor Expiry (hours)	72	Hours before unseen neighbors are pruned (3 days)

Operations (admin): the Enrichment panel's Advanced section has an L2 crawler row to run an immediate crawl cycle or reset the network's discovered-neighbor queue.

Device identity resolution:

Osprey automatically resolves L2 neighbors to existing devices in the topology by checking these identifiers in order:

Chassis ID -- matches the remote chassis ID against known device chassis IDs
SNMP target management IP -- matches the remote management IP against configured SNMP targets
Router ID -- matches the remote management IP against device router IDs
Interface IP -- matches the remote management IP against known interface IPs
Hostname -- case-insensitive match of the remote system name against device hostnames

Resolution runs at poll time (per-device) and via a background sweep every 5 minutes.

Interpreting L2 links -- physical vs. dot1Q subinterface:

LLDP/CDP describes neighbor connections. It does not prove which VLANs or traffic paths use a connection.

Some routers advertise both a physical port and its dot1Q subinterface. You might therefore see Et0/1 → Et0/1 and Et0/1 → Et0/1.100 for the same cable. Osprey combines these advertisements for display and keeps the original observations.

An Et0/1 ↔ Et0/1.100 observation does not mean tagged and untagged traffic share a broadcast domain. Use the protocol's area view to inspect Layer 3 separation. If the extra advertisement is unwanted, check whether your router supports disabling LLDP on that subinterface.

L2 canvas overlay:

When L2 data is available, click the L2 toggle button in the toolbar to display Layer 2 switches and links on the canvas alongside the IGP topology. See L2 Topology Overlay.

Note: L2 neighbor discovery requires SNMP targets to be configured. It runs during the regular SNMP discovery interval (default 6 hours).

Per-Network L2 Configuration

L2 discovery is configured directly per network. This lets different networks use different SNMP credentials and discovery behavior without a global L2 setting.

Configuring a network:

Open the network's Enrichment panel from its row in the sidebar.
Use the L2 Discovery and Switch Crawling cards to enable or disable each capability and set its interval. These are direct ON/OFF settings. In a network with EIGRP, L2 Discovery is locked on because EIGRP discovery depends on it.
Select the primary and optional fallback credential profile. Administrative changes require the admin role.

Available per-network settings:

Setting	Description
L2 Discovery	Enable or disable LLDP/CDP enrichment for this network
Switch Crawling	Enable or disable breadth-first L2 switch crawling for this network
Primary Credential	SNMP credential profile used for this network
Fallback Credential	Optional profile tried when the primary credentials fail

Create and manage profiles under Admin > Monitoring > Credential Profiles. The selectors offer None and the named profiles; None means no credential profile is selected for that slot.

L2 data management:

These actions require an administrator:

Clear L2 Data — hover over the network's sidebar row to find this button. It deletes the network's L2 neighbor and discovered-neighbor data; enabled discovery can populate it again.
Reset queue — open the network's Enrichment > Advanced section. It clears the switch crawler's discovered-target records so targets can be reconsidered, without deleting existing L2 neighbor data.

Setting Up BGP Monitoring (BMP)

Osprey receives BGP routing data via BMP (BGP Monitoring Protocol, RFC 7854). Your routers push BMP messages to Osprey's BMP server -- no polling required. This gives you visibility into BGP peers, routing tables, and AS path analysis.

Prerequisites:

The network hierarchy (Network, AS, Routing Domain) must already exist -- see above.
Your router must support BMP and be configured to send BMP to Osprey's IP on port 11019 (TCP).

Step 1 -- Configure BMP on the router:

On Cisco IOS-XR:

bmp server 1
 host 198.51.100.10 port 11019
 flapping-delay 60
!
router bgp 65000
 bmp server 1
  route-monitoring policy post inbound

On Arista EOS:

router bgp 65000
 neighbor 10.1.0.1
  bmp activate
!
management api bmp
 host 198.51.100.10 port 11019

Step 2 -- Create a BMP target in Osprey:

First, create a BGP protocol instance in the sidebar:

Hover over a network and click + > Add Protocol Instance.
Select BGP as the protocol.
Click Create.

Then add a BMP target:

Expand the BGP protocol instance in the sidebar.
Click the + icon and select Add Target.
Enter a name, the router's management IP, and select a RIB mode:
- loc_rib -- Best paths as computed by the router itself (most common)
- adj_rib_in_post -- All paths received from all peers (post-policy)
- none -- Accept BMP session but skip RIB processing
Click Create.

BMP targets can also be managed via the REST API:

Create: POST /api/v1/bgp/targets
List targets: GET /api/v1/bgp/targets?pi_id=...
Update: PUT /api/v1/bgp/targets/{id}
Toggle enable/disable: PUT /api/v1/bgp/targets/{id}/toggle
Delete: DELETE /api/v1/bgp/targets/{id}

Choose history recording in the target form:

History mode	Records
Best-path + peer sessions (default)	Best-path changes and peer session history.
Best-path only	Best-path changes.
Full — per-peer RIB	Candidate paths as well as best paths and sessions. Needed for historical alternatives and peer-failure analysis.
Off	No BGP history for this target.

RIB mode chooses the incoming route data; history mode chooses what Osprey retains for later analysis.

Step 3 -- Verify connectivity:

The target's status indicator in the sidebar changes:

Pending (grey) -- Waiting for the router to connect
Connected (green) -- BMP session established, receiving data
Error (red) -- Connection failed (check router config, firewall, port 11019)

Once connected, BGP peers appear within seconds and routes populate as Route Monitoring messages arrive. An End-of-RIB marker is available only for source/RIB-mode combinations that define and export one; do not treat its absence as proof that no routes were received. Right-click a BMP target in the sidebar to view its peers or routes directly.

Step 4 -- View BGP data:

BGP Peers: Reports > Routing > BGP Peers (or right-click a BMP target > Show Peers)
BGP Routes: Reports > Routing > BGP Routes (or right-click a BMP target > Show Routes)
Live updates: Peer state changes (up/down) and route count changes are pushed to the browser via WebSocket -- no page refresh needed.

Route reflectors: A reflector can provide a broad view of the AS, but its Loc-RIB contains its own selected routes. Visibility still depends on export policy, address families, and the routes the reflector receives. It is not every client's complete set of alternatives.

BMP Targets

BMP targets are managed directly from the sidebar. Create a BGP protocol instance (see Setting Up BGP Monitoring), then expand it in the sidebar to manage targets. Targets can also be managed via the REST API (/api/v1/bgp/targets).

Sidebar management:

Hover over a BGP protocol instance in the sidebar and click + > Add Target.
Enter a name, router IP, and RIB mode in the quick-add dialog.
The target appears under the protocol instance with a status indicator.
Right-click a target for Show Peers, Show Routes, or Copy Router IP.
Hover over its row to edit, enable/disable, or delete the target.

RIB modes: loc_rib (router's best paths), adj_rib_in_post (all received routes post-policy), none (peer monitoring only).

Status indicators: Pending (awaiting connection), Connected (green, active session), Disconnected, Error (red).

When a target is deleted, all associated BGP peers and RIB data are automatically removed.

Note: The BMP server listens on TCP port 11019 by default. Configure this in osprey.yaml under bmp.listen_address. The bmp.allowed_cidrs setting restricts which IPs can connect.

EVPN Visibility (automatic)

If your fabric runs EVPN (RFC 7432 -- EVPN-VXLAN or MPLS-based E-LAN / EVPN-VPWS), Osprey picks it up from the same BMP feed with no extra Osprey configuration: the moment BMP messages carry the EVPN address family (AFI 25 / SAFI 70), EVPN instances are discovered and a Reports > Routing > EVPN entry appears automatically.

The only requirement is on the router side: the BMP-exporting router must actually carry the EVPN routes. Make sure the EVPN address family is active on the sessions BMP monitors -- typically a route reflector that participates in the EVPN mesh. On a router that should see all EVPN routes regardless of its own route-target imports (a dedicated monitoring peer), disable RT filtering (e.g. no bgp default route-target filter on IOS-XE).

Each BMP target has an EVPN route budget (max_evpn_routes, API-configurable per target). If a target exceeds it, additional routes are dropped (withdrawals still process) and the EVPN panel shows the instance data as truncated -- never silently incomplete.

MPLS Discovery (TE Tunnels, L3VPNs & L2VPN Pseudowires)

Osprey discovers MPLS state from the routers over SNMP, inside the normal poll cycle — no extra service and no router configuration beyond SNMP access:

MPLS-TE tunnels (RFC 3812, MPLS-TE-STD-MIB): every tunnel with its role (head / transit / tail), admin/oper status, and signalling protocol.
L3VPNs (RFC 4364 / RFC 4382, MPLS-L3VPN-STD-MIB): per-PE VRFs with their route-targets, rolled up server-side into L3VPNs (a route-target equivalence class), classified full-mesh or hub-and-spoke with per-site hub/spoke roles.
L2VPN pseudowires (RFC 3985 / RFC 5601, PW-STD-MIB — with automatic fallback to the pre-standard CISCO-IETF-PW-MIB that IOS/IOS-XE actually implement): every pseudowire with its peer, attachment-circuit name, and per-end status, rolled up server-side into VPWS wires (point-to-point, both ends mutually paired) and VPLS instances (multipoint, classified from mesh evidence — never guessed).

Discovery switch — the MPLS Discovery card in the network's Enrichment panel (open it from the network row in the sidebar) controls discovery:

Setting	Behavior
On	A cheap capability probe runs on every SNMP target; only devices that answer the MPLS MIBs are walked
Off (default for new networks)	MPLS discovery is disabled for this network

There is no force-walk mode. Older networks that used the former Auto mode were migrated to On, preserving their probe-gated behavior.

Viewing the results: Open the report for the discovered service: MPLS-TE Tunnels, L3VPNs, VPWS Wires, or VPLS Instances. These entries appear when the corresponding data is available. Each report explains its status labels and canvas overlay.

A tunnel reroute/drop, a VRF going down, or a pseudowire going down feeds incident correlation as a symptom attached to the co-incident link/PE failure — never as a root cause. A pseudowire symptom carries both endpoint routers, so it attaches to an incident at either end of the wire.

4. The Topology Canvas

The topology canvas shows devices as nodes and routing adjacencies as links. Select areas in the sidebar to choose what to display. Changes arrive automatically: affected elements briefly flash, and a notification summarizes the update.

The topology canvas: routers coloured by area, the minimap bottom-right, and the bottom bar with layout selector, overlay pills and topology counts

Action	How
Pan	Click and drag on empty canvas
Zoom	Mouse wheel (scroll up = zoom in)
Zoom in/out	Click the +/- icons in the menu bar (top-right)
Node/label size	Click the circled ⊖/⊕ icons in the menu bar (top-right, left of search). Shrinks or enlarges all node icons and labels in place — positions and zoom stay put, so shrinking frees up room on the links for cost, interface and IP labels. Also available under View > Size as Size Down, Size Up, and Size Reset (restores 100%).
Fit to screen	Click the fit-to-screen icon in the menu bar (top-right)
Select device	Left-click a node (opens Node Detail Panel)
Select link	Left-click an edge (opens Link Detail Panel)
Context menu	Right-click a node or link
Search	Ctrl+K / Cmd+K (or Tools > Search)
Deselect	Left-click empty canvas (deselects; panels remain open)
Return to dashboard	Topology > Dashboard
Refresh topology	Topology > Refresh
Export	Topology > Export as PNG or Topology > Export as SVG. Exports use the current theme background color. If the grid is enabled (View > Grid), it is included in the export.

Selecting an Area

Use the sidebar (left panel) to navigate the hierarchy. Click an area (OSPF area or IS-IS level) to load its topology on the canvas. You can check/uncheck multiple areas within the same protocol instance to view them together. IS-IS levels appear in the sidebar as "Level 1" and "Level 2" instead of dotted-decimal area IDs.

The sidebar is resizable -- drag its right edge. Toggle it via View > Sidebar.

Right-click a device to access a categorized context menu with section headers:

Inspect section:

Action	Description
Inspect	Open the Node Detail Panel
Show events	Open Activity Tray filtered to this device
Show routing table	Open the IGP routing table viewer for this device (OSPF, IS-IS or EIGRP routes, labelled in each area's own vocabulary)
Show neighbors	Open the Neighbor Table panel for this device
View timeline	Open chronological event history for this device
SPF tree from here	View the Dijkstra shortest-path tree rooted at this device (see SPF Tree)

Routing section:

Action	Description
Set as route source	Mark as SPF path source (green highlight)
Set as route destination	Mark as SPF path destination (red highlight)

Layout section:

Action	Description
Hide [device name]	Remove from canvas (reversible via Unhide All)
Re-layout neighbors	Reapply layout to this device and its direct neighbors using the fCoSE algorithm. If multiple nodes are selected, this becomes "Re-layout N selected" and applies to all selected nodes.

Icons section:

Action	Description
Change icon...	Override this device's icon from the Icon Library
Reset icon	Revert to the default icon for this device type

Connect section:

Action	Description
SSH to [device name]	Open an SSH terminal session to this device (administrators and engineers only; live mode, enabled SSH proxy and IPv4 router ID required)

Export section (when 1+ nodes selected):

Action	Description
Export N selected > PNG	Export selected nodes and mutual edges as a PNG image
Export N selected > SVG	Export selected nodes and mutual edges as a vector SVG
Export N selected > Visio	Export selected nodes and mutual edges as a .vsdx file

Danger zone (below a separator):

Action	Description
Delete [device name]	Permanently remove the device from the topology. Admin only; enabled only when the device is stale or all its connected links are down. Requires confirmation.

Right-click a link for:

Action	Description
Inspect link	Open the Link Detail Panel
Show events	Open Activity Tray filtered to this link
View timeline	Open chronological event history for this link
Delete link	Permanently remove the link. Admin only; enabled only when the link is down or stale. Requires confirmation.

Layout

Osprey uses force-directed layout by default. The bottom bar contains the layout toolbar on the left side and status indicators on the right side.

Layout algorithm dropdown (four options):

Force-Directed (default): Automatically spreads devices according to their connections.
Geometric: Places devices on a grid with right-angle connections.
Octilinear: Similar to Geometric, with 45-degree diagonals allowed.
Circle: Arranges devices in a circle.

Layout actions in the bottom bar:

Re-layout runs the selected algorithm again.
Layout picker opens the shared library. The same layouts are available whether you open one area, a whole network, or several networks together. Existing layouts appear here too. The owner's name helps distinguish layouts with the same name.
Save updates your active layout. Administrators can also update another user's layout. For everyone else, Save asks for a name and creates a separate copy. A warning dot means there are unsaved changes.
The arrow beside Save offers Save as new layout... and Revert to saved positions. Saving from a smaller selection preserves the saved positions and hidden nodes outside that selection. Save as also preserves these when copying an existing layout, and never overwrites a layout just because its name matches.

A layout saves node positions, zoom and pan, hidden nodes, and node/label size. Dragging a node or changing its size marks the active layout as modified.

Snap-to-grid: Enable the "Snap" checkbox in the bottom bar to lock dragged nodes to a grid. Choose grid spacing (10px, 20px, or 40px) from the adjacent dropdown.

Drag nodes to adjust their position, then save when you are happy with the arrangement.

Arrange the topology and choose Save as new layout.... Give the layout a name that tells colleagues what it is for.
An administrator can open the layout picker and click the star, Set as shared default.
Other users can select it from the same library. It opens automatically for users who have not chosen a layout themselves. Choosing another layout changes only their own selection.

The shared default is marked (default). Changing networks or areas does not change your chosen layout. Devices with saved positions keep them; devices the layout does not cover receive an initial position that you can adjust.

Delete or Restore a Layout

The owner or an administrator can click the X beside a layout. Osprey asks for confirmation, then moves it to Deleted layouts… in the same picker. Other users can no longer select it.

To recover it, open Deleted layouts… and click Restore beside its name. Owners can restore their own layouts; administrators can restore any layout. Positions and other saved settings are preserved. If its name has been reused, the recovered layout gets a distinct name. Restoring does not replace the current shared default; an administrator can set it as the default again.

Deleted layouts stay recoverable without a database restore. This applies to deletions made with this feature; it cannot recover layouts permanently deleted by older versions.

MiniMap

A minimap overlay appears in the bottom-right corner of the canvas when enabled. It shows a bird's-eye view of the entire graph with:

Colored dots for nodes (blue for normal, orange for ABRs, red for down devices)
Gray lines for edges
A blue rectangle indicating the currently visible viewport area

Click or drag on the minimap to pan the main canvas to that location.

Node Appearance

A node's icon indicates its role: router, ABR/L1L2, ASBR, combined role, or recorder. Its label follows View > Node Labels. Color follows View > Color; built-in icons adapt to area colors.

Use View > Size or the circled ⊖/⊕ buttons to change icon and label size without moving nodes. Smaller icons leave more room for link labels. The size is saved with a layout; without an active layout it returns to 100% after reload.

Stale devices are dimmed. Devices affected by a topology update flash briefly.

Link Appearance

Appearance	Meaning
Solid line	The link is up.
Dashed red	The link is down. For a merged link, every member protocol is down.
Dashed in the normal area color	A merged link is degraded: some protocols are down, while others remain up.
Dashed and dimmed	The link's area data is stale. A merged link is dimmed only when all of its contributing areas are stale.

Use View > Link Labels to show costs, interface names, or addresses. Asymmetric costs show both directions. Large IS-IS metrics are abbreviated, such as 10K or 1.2M.

When SNMP identifies the same physical interface for several protocol links, Osprey merges them into one slightly thicker edge. A suffix such as [2P] identifies multiple protocol instances; [L1L2] identifies both levels of one IS-IS instance. Hover or open link details to compare each protocol's cost and state. Without the required interface mapping, links remain separate.

Collectors on the Canvas

Osprey's own recorder nodes are hidden by default. To show them, clear View > Filters > Hide Recorders. They appear as muted, dashed nodes near their monitored routers.

Recorder tunnel links are displayed as up and excluded from ordinary link-failure diagnostics. Use the recorder's sidebar status to assess collection health. Recorder nodes are also excluded from the license count and device diagnostics.

L2 Topology Overlay

The L2 toggle button in the toolbar renders discovered switches and L2 adjacencies on the topology canvas as an overlay alongside the L3 IGP topology (OSPF or IS-IS).

What it shows:

L2 switches appear as dashed-border nodes, positioned near their connected L3 routers.
L2 links appear as dashed gray edges between switches and between switches and routers.
Router-to-router L2 edges are suppressed -- only edges to L2-only devices are shown (avoids duplicating the existing OSPF links).

Interaction:

Click an L2 edge to open the L2 Link Detail Panel, showing LLDP/CDP adjacency details, capabilities, and protocol.
Where parallel L2 links are grouped under a LAG marker, click it to inspect the member links and ports. The grouping does not by itself prove that the devices have configured a port channel.
Right-click context menu guards prevent actions that do not apply to L2-only devices (RIB, SSH, SPF tree).
L2 topology auto-refreshes via WebSocket when changes are detected.

Area Cloud Overview

When viewing large multi-area topologies, Osprey can display an aggregated "cloud view" that shows each area as a stylized cumulus cloud instead of rendering every individual device. This provides a high-level overview of inter-area connectivity without overwhelming the canvas with hundreds of nodes.

Activating cloud view:

Automatic: When 10 or more areas are checked in the sidebar, cloud view activates automatically. The threshold is configurable via Admin > System Settings > Display > Area cloud auto-threshold.
Manual: Toggle View > Area Cloud Overview or click the cloud icon in the toolbar to switch between cloud view and full topology.
Per-user preference: Your explicit toggle overrides the auto-threshold until you reset it.

Cloud appearance:

Each area appears as a colored cumulus cloud shape, sized proportionally to its device count (200-440px based on log scale).
The cloud label shows the area ID, device count, and alert count (if any).
Cloud border style indicates area type: solid for normal areas, dashed for stub, dot-dash for NSSA, long-dash for totally stubby.
Health status is indicated by border color: green (healthy), yellow (warning), red (critical).

Inter-area edges:

Bundled edges connect clouds that share ABRs. Edge thickness scales with the number of ABRs.
Hover an edge to see the connected areas and ABR count.
Virtual link edges are labeled "VL" with a distinctive style.

ABR nodes:

ABRs appear as smaller nodes between the clouds they connect.
ABR labels show hostname (or router ID if no hostname).
ABR role badges indicate: ABR, ASBR, L1/L2, or combined roles.

Interacting with clouds:

Action	Result
Single-click	Opens the Area Detail Panel showing device/link counts, health, alerts, and connected ABRs
Double-click	Expands the cloud in place, revealing all devices inside with animated transition
Right-click	Context menu: Expand/Collapse, Open Detail Panel, Hide Area, Open LSDB
Hover	After a short, deliberate pause, shows a popup with area stats: devices, intra-area links, inter-area edges, ABRs, alerts (hidden while a context menu is open)

Expanded clouds:

When you double-click a cloud, it expands to show the area's devices rendered inside a dashed hull boundary.
The cloud background fades out and child nodes fade in over 250ms (two-phase animation).
Double-click again to collapse back to the cloud view.
Use the context menu's "Collapse area" or press Escape to collapse all expanded areas.
Expansion state is preserved while in cloud view but resets when switching to full topology.

Performance:

Animations are skipped when more than 3 areas are expanded simultaneously.
Osprey respects your browser or operating system preference for reduced motion.

Accessibility:

Full keyboard navigation: Tab through clouds, Enter to expand/collapse, Space to open panel, Escape to collapse all, Arrow keys to navigate between clouds.
Screen reader accessible with ARIA labels: "Area {label}, {count} devices, health {status}, {n} alerts".
Focus indicators appear as visible borders around the focused cloud.

In time travel: clouds show device and link counts from the selected time's snapshots. Alert and incident counts follow their recorded active periods. An area without a snapshot at that time appears empty; that alone does not prove the area did not exist.

Topology Export

Open the Topology menu to export the canvas as PNG, SVG, or Visio. You can also export a selection from the context menu.

PNG Export

Topology > Export as PNG

Exports the current canvas view as a raster image:

All visible nodes, edges, labels, and area boundary hulls are included.
The background uses the active theme color (dark or light).
If the grid is enabled (View > Grid), the grid pattern is rendered in the export.
Area boundaries (colored convex hulls) are included if area coloring is active.
Output resolution matches the canvas viewport.

SVG Export

Topology > Export as SVG

Exports the canvas as a scalable vector graphic:

Same content as PNG (nodes, edges, labels, area boundaries, grid).
Vector output — scales to any size without loss of quality.
Theme-aware: background and element colors match the active theme.
Suitable for embedding in reports, presentations, or printing.

Visio Export

Topology > Export as Visio

Generates a native Microsoft Visio (.vsdx) file that reproduces the on-screen topology almost exactly (background and grid excluded):

Canvas-faithful geometry: the browser captures the live layout — exact edge curves (including parallel/LAG bows), border-clipped endpoints, and area-boundary hulls — and the server reproduces them. Links are true bezier curves, not straight lines.
Edge-label chips: cost, interface names and subnets render as the canvas's labels, rotated along each link and kept upright.
Connection points: every device carries Visio connection points (center + cardinal edges), so the diagram stays connectable/editable in Visio.
Area boundaries: when area boundaries are shown on the canvas, area hulls are drawn as area-colored dashed regions with labels.
A4 landscape page with title block and legend.
Icon packs: Builtin (Clarity/Industrial) and imported Visio stencil packs are supported. The export uses the active icon pack from the toolbar.
Per-device overrides: If you assigned a custom icon to a specific device (right-click > Change icon), that override is rendered in the Visio file.
Per-type defaults: Device-type role mappings from the Icon Library (e.g. all routers use a specific stencil icon) are respected.
Priority: Per-device override > per-type default > active pack fallback.
Imported vendor stencil icons render as-is (multi-color), matching the canvas behavior.
Hidden nodes are excluded from the export.
Requires at least one area selected in the sidebar.

Selection Export

Select one or more nodes on the canvas (shift-click or box-drag), then right-click to open the context menu. The Export N selected submenu offers:

PNG — Raster image of only the selected nodes and their mutual edges. Non-selected elements are excluded; the bounding box fits the selection.
SVG — Vector graphic of the selection. Same filtering as PNG: only selected nodes, connecting edges, and relevant area hulls.
Visio — Server-side .vsdx containing only the selected devices and their mutual links. Useful for extracting a subnet or site from a larger topology into a Visio diagram.

Both L3 (router) and L2 (switch) nodes can be selected and exported together. Edges that connect a selected node to a non-selected node are excluded.

5. View Controls

All view settings are accessed from the View menu in the menu bar.

Renderer preference

Open View > Renderer to choose how Osprey draws the topology:

Canvas is the default and recommended option.
WebGL — Beta (not recommended) is experimental. Some status indicators and path markings may be missing, icons may be less sharp, and labels may briefly disappear.

To switch, select an option, save any layout or form changes, then reload the browser tab. The new renderer takes effect after the reload.

Osprey remembers your choice for your account in this browser, including new tabs and future visits. Tabs that are already open apply the change when you reload them. Other users, browsers and devices keep their own preference.

Cloud View Toggle

Toggle View > Area Cloud Overview to switch between cloud view (aggregated areas) and full topology (all devices). See Area Cloud Overview in Section 4 for details. The toggle state persists across sessions. When auto-activated by threshold, you can manually toggle off to see the full topology.

Area cloud overview: each OSPF area drawn as one coloured cloud around the backbone area 0.0.0.0, with the inter-area link count on each connection

Node Labels

Mode	Shows
System Default	Uses the admin-configured display name mode (see Admin > System Settings > Display)
SNMP Hostname	Device hostname from SNMP sysName
DNS Hostname	Reverse DNS (PTR) name
Router ID	OSPF router ID (IPv4 address) or IS-IS system ID (XXXX.XXXX.XXXX)
Hostname (IP)	Hostname with router ID in parentheses
Area ID	OSPF area ID for the device's primary area
No Labels	Hides all node labels

Link Labels

Three independent toggles (can be combined):

Cost: IGP metric cost (forward/reverse if asymmetric). OSPF cost or IS-IS wide metric.
Interface Names: SNMP-discovered interface names (abbreviated, e.g., Gi0/0/1).
IP Addresses: Endpoint IPs with CIDR notation.

Color Modes

Mode	Description
By Area	Each OSPF area or IS-IS level gets a distinct color. Builtin pack icons are recolored to match; imported packs keep original colors. Edges always colored by area.
By Metric Cost	Gradient from green (low cost) to red (high cost)
By Utilization	Heatmap based on SNMP traffic data (green 0% to yellow 50% to red 100%)
Uncolor	All nodes/links use default neutral styling

Utilization coloring requires SNMP targets to be configured and polling. It auto-refreshes every 15 seconds. In time travel it is unavailable: the canvas drops the coloring entirely rather than painting live rates onto a historical topology — blank means not available at that time, not zero traffic.

Themes

Osprey supports twelve color themes. Select via View > Theme:

Theme	Description
Dark	Default dark theme
Midnight	Deep desaturated blue-grey with steel teal accent
Morning	Soft warm light with sunrise palette
Solarized	Low-contrast Solarized scientific palette
Gruvbox	Retro warm earth tones
Warm Slate	Muted warm-grey professional theme
Miami	Vibrant 1980s pink and teal
Horizon	Warm neutral light with professional blue accent
Alphabet	Light sky-blue blueprint
Daylight	Bright light theme for high-ambient environments
Sakura	Soft pink cherry-blossom light theme
High Contrast	Maximum contrast for accessibility (WCAG AAA)

The canvas, panels, and terminal all follow the selected theme.

Icon Packs

Choose a pack under View > Icons:

Pack	Appearance
Clarity (default)	Flat router symbols with separate role badges.
Industrial	Traditional network-equipment symbols.
Osprey 3D	Shaded router and switch icons, with a symbol for each role.
Imported packs	Custom icons imported from Visio `.vssx` stencils.

Area coloring: All three builtin packs recolor icons by OSPF area or IS-IS level — Clarity and Industrial substitute their brand color, Osprey 3D tints the face of its pucks. Imported packs preserve their original brand colors on the canvas — only edges are colored by area.

The selected icon pack, per-device-type defaults, and per-device icon overrides are all carried into Visio exports — the exported .vsdx matches the canvas appearance.

Importing Custom Icon Packs (Admin)

Open View > Icons > Icon Library....
Click "Import Stencil" in the Icon Library panel.
Select a .vssx Visio stencil file. The file is uploaded and each master shape is converted to SVG.
The new pack appears in the View > Icons submenu and can be selected immediately.

Vendor stencils from Cisco, Juniper, Arista, Fortinet, and others are supported. Both geometry-based shapes and EMF-embedded icons are converted.

Assigning Icons to Roles

To set defaults for an imported pack, open Icon Library, select a role (Router, ABR, ASBR, ABR+ASBR, or Switch), then click an icon. Unassign removes a role assignment. To use the same artwork for a second role, duplicate the icon and assign the copy. Administrators can delete imported packs from the library; this removes the pack, not just its selection on your canvas.

Per-Device Icon Overrides

Right-click any device on the canvas to access icon overrides:

Change icon... — Opens the Icon Library panel. Select any icon from any pack to override this device's icon.
Reset icon — Removes the per-device override, reverting to the pack's default icon for this device type.

Overrides are stored in your user settings and persist across sessions.

Hiding Nodes

You can hide devices from the canvas:

Right-click > Hide: Hides a single device.
View > Filters > Hide Leaf Nodes: Hides devices with one or fewer links.
View > Filters > Hide Failed Nodes: Hides isolated/unreachable devices.
View > Filters > Hide Unconnected: Hides devices with zero connected edges.
View > Filters > Vendor: Filter to show only a specific vendor. A submenu lists all discovered vendors; select one, or choose "All Vendors" to reset.
View > Filters > Role: Choose ABRs Only or ASBRs Only. Select All Roles to reset.
View > Filters > Unhide All: Resets all filters at once (also available in the bottom bar).

Hidden nodes are indicated by an "Unhide (N)" badge in the bottom bar. Click it to restore all hidden nodes.

Area Boundaries

Toggle View > Area Boundaries to draw colored translucent hull overlays around each OSPF area's or IS-IS level's devices, visualizing area containment. The hulls automatically redraw as you pan, zoom, or move nodes. This setting persists across sessions via user settings.

Grid Background

Toggle View > Grid to show a dot-grid background on the canvas. This is a visual aid for manual node placement and works independently of the snap-to-grid feature in the bottom bar.

Panel Toggles

The View menu also contains toggles for UI panels:

Grid: Show/hide the dot-grid background.
Area Boundaries: Show/hide colored area hull overlays.
L2 Devices: Show/hide the L2 topology overlay (only appears when L2 data is available).
Sidebar: Show/hide the left hierarchy navigation panel.
Activity: Show/hide the activity tray (events, alerts, logs).

Panel Management

Detail views, reports, tools, and terminals open as floating panels. You can keep several visible while working with the canvas.

Key behaviors:

Multiple panels: Up to 3 panels can be open at once. Opening a 4th panel automatically minimizes the least-recently-used panel to make room. Up to 16 total panels (open + minimized) are tracked; exceeding this limit auto-closes the oldest minimized panel.
Title bar: Every panel has a title bar with the panel title, a minimize button, and a close button. Drag the title bar to reposition the panel.
Minimize / Restore: Click the minimize button (or press Escape) to collapse a panel to a compact pill in the pill bar at the bottom of the screen. The panel keeps its scroll position, column settings, and form input. Click the pill to restore the panel to its previous position and size.
Resize: Drag any edge or corner of a panel to resize it (dual-edge handles). Each panel type has its own minimum size constraint.
Z-ordering: Click any panel to bring it to the front. Panels maintain a stacking order; the most recently interacted panel is always on top.
Cascade positioning: New panels spawn at the right edge of the viewport and cascade leftward with 24px offsets, avoiding overlap with the sidebar and previously opened panels.

Keyboard shortcuts:

Shortcut	Action
`Escape`	Minimize the focused panel
`Shift+Escape`	Close the focused panel
`Ctrl+Shift+M`	Minimize all open panels (clear the canvas)
`Ctrl+Shift+R`	Restore all minimized panels

The same controls apply to report panels, device and link details, terminals, path details, traffic graphs, and the Icon Library.

Help without losing your place

Question-mark buttons explain a field, column or method. Click or tap one, or focus it and press Enter/Space. Longer explanations open inside the panel. Escape closes the help before affecting the panel. Your input is preserved.

Shortened values are not help: hover or focus the value itself to read its full text in a selectable balloon, or hold it on touch. The same applies to exact timestamps behind relative ages and full software banners. A fully visible value with no additional detail does not add another keyboard stop.

Action buttons show a short description on hover or keyboard focus. On touch, hold the control to read the description; a normal tap still performs its action. Warnings, required formats and limitations of a result stay visible without opening help.

Help does not resize the window. Scroll inside the panel, or resize it yourself. System Settings stacks its fields and changes to horizontal section navigation when space is narrow. Topic links open this guide in a separate tab, using your current theme, so you can consult a procedure without leaving your work.

Activity Tray

The Activity Tray is a collapsible panel anchored to the bottom-left of the screen. It provides real-time visibility into topology events, alerts, and application logs. Resize it vertically by dragging its top edge.

The tray has two tabs for all users, and a third admin-only tab:

Events: Live topology events (device/link additions, removals, state changes) and correlated incidents. Events arrive via WebSocket in real time. New events trigger a badge count and the list auto-scrolls to the latest entry.
Alerts: Currently firing and acknowledged alerts with severity badges. Acknowledge or resolve alerts directly from this tab.
Logs (admin only): Real-time application log viewer streaming logs from all Osprey services (engine, API, collector-manager, SNMP poller, recorders). Includes level filtering (debug/info/warn/error), service filtering, and text search. Consecutive identical log messages are collapsed with a "(message repeated N times)" counter to reduce noise. Auto-scroll can be toggled on/off.

Tip: The Logs tab replaces the need for journalctl for day-to-day operational debugging directly from the browser.

IS-IS Event Types

IS-IS topology changes generate events similar to OSPF but with IS-IS-specific types:

LSP Update: An IS-IS Link State PDU was updated (analogous to OSPF LSA Update).
LSP Purge: An LSP was purged from the LSDB (analogous to LSA MaxAge).
IS-IS Adjacency Change: An IS-IS adjacency transitioned state (up/down).
DIS Change: The Designated Intermediate System changed on a broadcast segment (analogous to OSPF DR Change).

These events appear in the Activity Tray, event history, and incident correlation alongside OSPF events.

6. Device & Link Inspection

Hover Tooltips

Hover over a device or a link on the canvas for a compact at-a-glance card (no click needed). After a brief delay the tooltip shows:

Node: name + health dot + role badge (ABR/ASBR/Collector), the other identifier (router ID / system ID) and vendor/platform, area memberships, link count (with how many are down), and device type.
Single link: endpoints and interface pair, protocol and area, cost (forward/reverse when asymmetric), link type and speed.
Multi-protocol (merged) link: one aligned row per protocol with its area, cost, and up/down state.

Click the device or link to open its full detail panel.

Picking up a node closes hover cards immediately. No node, link or area cards appear while you drag. After releasing the node, move away and hover again to show a card.

SRv6 and Local Repair

The SRv6 tab appears on live IS-IS devices with advertised SRv6 capabilities, locators or adjacency SIDs. It groups capabilities, named maximum SID depths, locators and End/End.X SIDs by area. The area UUID remains available on hover. These are live observations; historical views explain that this information is unavailable at the selected time.

Within a live SRv6 observation, Calculate local repair lets you select a destination router and a failed local link or neighbor. The calculation uses one IS-IS area's ordinary metrics and checks all equal-cost branches. It shows the post-failure path, outgoing circuit, ordinary LFA neighbors and any logical node/adjacency instructions needed before the original destination segment. The result also attempts to bind each instruction to an advertised End/End.X SID in topology 0, algorithm 0. Missing, ambiguous or unsupported evidence has an explanation. A destination End candidate is separate from the unobserved original packet destination. The depth table compares minimum requirements with node MSD advertisements; link overrides and the original packet's complete segment list remain unverified. A match is not an installed TI-LFA verdict. Changing an input clears the old result. Missing or truncated inputs are shown as errors, not protection verdicts.

Multi-Protocol Devices

The same physical device can run both OSPF and IS-IS simultaneously. Osprey automatically correlates devices across protocols using TE Router ID (IS-IS TLV 134) and SNMP sysName matching. Each protocol is managed under its own protocol instance in the sidebar.

The canvas can show checked areas from multiple protocol instances together. When SNMP identifies a shared physical interface, Osprey merges its protocol links into one edge. Open the link details to compare protocols. A path query or simulation still uses its selected protocol instance.

Node Detail Panel

Click any device on the canvas to open the Node Detail Panel -- a floating, draggable, resizable panel managed by the Panel Manager. It appears over the canvas and can be repositioned, minimized to the pill bar, or resized via dual-edge handles (see Panel Management).

Read about the Overview, Interfaces, Neighbors, and Traffic tabs, or the shared alerts and actions.

Node Detail Panel showing a router's identity, the protocols and areas it participates in, and its hardware and software details

Title bar: Shows the device name, state, and protocol/role badges. Drag it to move the panel. Use the buttons to minimize or close it; Escape minimizes and Shift+Escape closes.

Device Overview Tab

Identity: Router ID, IS-IS System ID/NET where applicable, management address, and DNS name. The management-address label explains how the address was selected.
Protocols & Areas: Each routing process and its areas or levels, with its role badges. EIGRP shows its AS and address family.
Hardware: Device type, vendor, model, platform, software, and available protocol capabilities.
Evidence: How Osprey obtained the information: LSDB read, MIB reported, or Router exported.

Device Interfaces Tab

Lists interface names and addresses, including IPv4 and IPv6 where available, and discovered LLDP/CDP neighbors.

Device Neighbors Tab

Lists connected devices with their protocols, areas or levels, state, and costs. A neighbor reached through multiple protocols appears once with a badge for each protocol. Click a neighbor to open its details.

Device Traffic Tab

When SNMP data is available, shows interface rates, utilization, and errors, ordered by utilization. Loopbacks are excluded from the traffic totals. Opening the tab activates 10-second boost polling. Click an interface for its utilization history and choose 24h, 7d, or 30d.

Device Alerts and Actions

Collapsible Alerts and Events sections remain available across tabs. They show up to 25 unresolved alerts and 10 recent events. Hover a relative timestamp for the full UTC time.

A red CRITICAL — Device Down banner means all of the device's links are down in the displayed topology. In Time Travel, it reflects the selected historical state. Additional protocol tabs, such as EIGRP, appear when data is available.

Quick action buttons (pinned at the bottom of the panel):

SSH: Open an SSH terminal session to this device. Shown only to administrators and engineers in live mode when the SSH proxy is enabled and the router ID is IPv4; operators never receive terminal access.
Route Src: Set this device as the SPF path source
Route Dst: Set this device as the SPF path destination

Note: Additional actions (Show events, Show routing table, Show neighbors) are available via the right-click context menu, not from the panel footer.

Link Detail Panel

Click any link on the canvas to open the Link Detail Panel -- a floating, draggable, resizable panel managed by the Panel Manager (same behavior as the Node Detail Panel).

Link Detail Panel for a wire carrying both OSPFv2 and OSPFv3: a tab per protocol, each protocol's own area and cost, both endpoints with their interfaces and dual-stack addressing, and live traffic graphs

Header (drag handle): Shows the link state (green/red dot), source and target hostnames connected by an arrow, and router IDs beneath if hostnames are available. Drag the header bar to reposition the panel anywhere on screen.

Critical state banner: When the link state is down, a red "CRITICAL -- Link Down" banner appears below the header. This is derived from live topology state, not from alert rules, and also works during time-travel playback.

Link metrics: Link type (P2P, broadcast, etc.) and IGP cost (OSPF cost or IS-IS metric). Asymmetric costs are displayed with both forward and reverse values plus an "asym" warning badge.

Link Protocol Tabs

Multi-protocol tabs (merged edges only): When a link carries multiple protocols (e.g., OSPFv2 + OSPFv3 + IS-IS on the same wire), a tab bar appears below the header with a Physical tab and one tab per protocol. Each protocol tab shows a state dot (green/red). Single-protocol links display the standard layout without tabs.

Physical tab (default): Protocol comparison table showing each protocol's area, cost, and state. Endpoint identities (A/Z with hostname and router ID). Shared physical metadata: DNS, MTU, first seen.
Per-protocol tabs (e.g., "OSPFv2", "IS-IS"): Protocol-specific addressing (dual-stack IPv4/IPv6 for OSPF; IPv4/IPv6 plus the system ID for IS-IS), cost, link type, and auth type. Timer mismatches are shown as inline warnings only when the two sides disagree — no timer section when everything matches. Detail is lazy-loaded per tab.

Link Endpoints and Timers

Endpoints (A/Z) (single-protocol links): Each endpoint is displayed in a compact card showing:

Endpoint label (A or Z), device hostname (clickable -- navigates to the Node Detail Panel), and router ID
Interface name, IP address with CIDR mask, and interface alias/description if available
Interface speed displayed on the right

IGP Timers (single-protocol links): A side-by-side comparison table of timer settings for both endpoints. For OSPF: Hello Interval, Dead Interval, Auth Type, Network Type, Cost, and Speed. For IS-IS: Hello Interval, Hold Time, Metric, Circuit Type, and Speed. Mismatches are highlighted in amber with a warning icon. Requires the SNMP poller to have walked the OSPF-MIB or ISIS-MIB interface table.

Link Traffic and Errors

Traffic section (when SNMP is configured):

Bidirectional display: A-to-Z direction (source device's outbound) and Z-to-A direction (target device's outbound)
Each direction shows: device names with a directional arrow, real-time rate in bps, a sparkline chart with historical data points, and PPS count
Combined utilization bar showing the maximum utilization of both endpoints
Traffic data is updated via REST polling and WebSocket push, with automatic 10-second SNMP boost while the panel is open
Utilization History: A period-selectable chart (24h, 7d, 30d) showing utilization trends for both endpoints. Color-coded area chart with threshold and average markers.

Errors section (shown only when errors or discards are detected):

Per-endpoint error and discard counters: In Errors, Out Errors (with rate per second), In Discards, Out Discards
Highlighted with a red background and border for visibility

Link Alerts and Actions

Alerts section (collapsible, lazy-loaded):

Shows non-resolved alerts (firing + acknowledged) for the link's endpoint devices, up to 25
Click to expand; alerts are fetched on first expansion only

Events section (collapsible, lazy-loaded):

Click to expand. Events are fetched from the API on first expansion only.
Shows up to 10 recent events for both endpoint devices, deduplicated and sorted by time

Quick action buttons (pinned at the bottom):

Inspect [source name]: Open the source device's Node Detail Panel
Inspect [target name]: Open the target device's Node Detail Panel

Resize: Drag any edge or corner handle to resize the panel. Minimum size is 360x360 pixels; default is 504x624 pixels.

Close with the X button or press Shift+Escape. Press Escape to minimize to the pill bar.

Traffic Graphs (MRTG-Style)

Per-interface historical traffic charts provide classic MRTG-style visualization of bandwidth usage over time. Access them from:

Edge context menu: Right-click a link and select Traffic: <interface-name> -- one menu item appears per endpoint interface.
Link Detail Panel: Click the Traffic A or Traffic Z buttons in the traffic section.

The chart renders as an inline SVG with the classic MRTG dual-area layout:

Green area (above baseline): Inbound traffic rate.
Blue area (mirrored below baseline): Outbound traffic rate.
Time window selector: Choose from 24h, 7d, or 30d to adjust the visible history.

Below the chart, summary statistics are displayed:

Metric	Description
Max In / Max Out	Peak inbound and outbound rates in the period
Avg In / Avg Out	Average inbound and outbound rates
Errors	Total in/out error count
Utilization	Peak utilization percentage

Traffic history comes from hourly SNMP summaries. Longer time windows (7d, 30d) provide a broader trend view at hourly granularity.

Tip: Traffic graphs require SNMP targets to be configured and the SNMP poller to have collected at least one discovery+counter cycle. If no historical data is available, the chart area displays a "No data" message.

Device and Link Timelines

Right-click a device or link and choose View timeline to inspect its recorded changes. The default window is 24h; choose 1h, 6h, 7d, or 30d for another period. Device timelines include related events, and the panel loads up to 200 events per query.

Use the timeline to find when a change was recorded, then use Time Travel to inspect historical topology. Opening a timeline does not itself switch the canvas into the past. An empty result means no matching events were returned for that scope and window, not proof that nothing happened outside recording coverage.

SPF Path Visualization

To visualize the shortest path between two devices:

Right-click the source device and select Set as route source (or click the Route Src button in the Node Detail Panel).
Right-click the destination and select Set as route destination (or click the Route Dst button).
The path is highlighted on the canvas. A Route Path overlay appears in the top-left corner of the canvas showing:
- Source device (green dot) and destination device (red dot)
- Forward path total cost and hop count (orange)
- Reverse path total cost and hop count (blue)
- An "Asymmetric routing detected" warning if forward and reverse costs differ or actually traverse different routers -- an ECMP tie can split the two directions across equal-cost branches with the same total cost, and the warning catches that case too, not just a cost difference
- A Clear button to remove the path visualization

You can set source and destination independently -- the path is computed automatically once both are set. Both directions are computed separately, so a genuinely asymmetric path shows as one.

A computed path highlighted across the canvas, with the Route Path overlay showing source, destination, and the forward and reverse cost and hop count

Expanding Details turns the overlay into a hop-by-hop table -- per hop the ingress and egress interface, the route type the router installed, and its own metric -- and Explain adds the reasoning underneath.

The Route Path hop table: one row per router with its ingress and egress interfaces, installed route type and metric

EIGRP paths to a network

When both IPv4 and IPv6 areas are selected, the destination network determines which family a prefix question uses; selecting a source address is optional. A contradictory address or family selection is rejected. Equivalent IPv6 spellings are accepted. If the network is already connected to the source and this view cannot draw a local path, the explanation states that explicitly.

A live EIGRP prefix result shows PATH TO NETWORK when the observed route chain reaches the requested connected network. Open Explain for its limits: this does not establish delivery to a particular address or device. Alternatives may have different metrics; an installation warning means Osprey cannot confirm that every displayed next hop was installed. Missing or inconsistent route data can prevent reconstruction even when the router has a route. Historical prefix requests do not yet use this connection.

For a network question with both address families selected, a source outside those areas is reported as outside the selection. A source with only the other address family is reported as lacking the requested family in that selection. Neither message means that the device is missing. For a historical network question, this check uses the source’s area membership at the requested time. If an EIGRP route cannot be reconstructed, another protocol's answer is warned only when the missing EIGRP information could change which route wins. An unreadable source route table is treated as unknown, not as proof that no EIGRP route exists.

Equal-Cost Paths (ECMP)

When a direction has more than one equal-cost path, an equal-cost strip appears in the overlay for that direction (orange for forward, blue for reverse): a count ("8 equal-cost paths"), an All button, and one numbered button per path. All — the default — draws every branch at once; clicking a number isolates that single variant on the canvas, and hovering one previews it without committing. The strip is labelled per-flow hash as a reminder of what ECMP means on the wire: which member a real flow rides is decided by each router's per-flow hash, so no single drawn branch is "the" path.

Osprey combines independent branch points and shows up to 8 distinct paths. For example, three successive two-way choices can produce eight variants. If more exist, the panel states that only the first eight are shown. A ×N badge in a hop table indicates the size of that hop's equal-cost next-hop set.

What the drawn path means

Read the path's explanation before treating a highlighted line as a forwarding result. Osprey uses different models depending on the protocol and available data.

Path model	What the result means
OSPF hop-by-hop	Reconstructs each router's route choice toward the destination from the recorded link-state data, when the query meets the model's requirements.
Shortest-path projection	Shows a source-rooted SPF path. It does not establish every intermediate router's forwarding choice. Used for IS-IS and OSPF queries where hop-by-hop reconstruction is unavailable.
EIGRP observed path	Follows forwarding choices reported by the routers through SNMP. Missing router data can leave the chain incomplete.

For a live OSPF inter-area prefix with an explicit destination address, Osprey can reconstruct each intermediate router's choice when the available data passes its consistency checks. The source's route metric and preference stay the same. The path ends at a router connected to the destination network; a warning makes clear that this does not prove delivery to the address itself. Completed equal-cost alternatives are shown within the normal display limits.

When those checks cannot be met, the displayed summary path still ends at the router advertising the summary. Its metric describes the source's route; a correct metric alone does not establish the onward forwarding path. The explanation identifies this fallback as a source projection.

For a live IPv6 path across networks, the final EIGRP section follows the selected IPv6 address. It may end at a router connected to the destination subnet rather than at the selected device itself. In that case the explanation names the last router, and a warning says the final device hop is unverified. This is not proof of packet delivery or of every recorded next hop being in use.

OSPFv2 cost and hop details:

Total cost is the source router's route metric, including the destination loopback cost. It can differ from the sum of the traversed link costs. The panel explains the difference when this occurs.
The Route column shows the route type and metric reconstructed for each hop. Intermediate routers can choose a different continuation from the one priced by the source, especially across area borders.
✓ proven identifies a next hop justified by the model's routing rules. It establishes membership in the possible installed set, not that a particular flow takes that branch.
↑ marks a rise in the per-hop route metric. This can follow from different area-border decisions and is not necessarily a display error.
An incomplete chain names the stopping reason: missing route, unknown next hop, loop, missing area coverage, or an unsupported construct.

In Simulation, link-state paths use shortest-path projections for both the baseline and changed topology, so the comparison uses the same model. EIGRP can retain a recorded primary or installed ECMP branch after a simulated failure. If no installed branch survives, or a change could attract an unrecorded route, the affected segment is unknown. Osprey does not simulate a new DUAL computation.

Protocol Toggle (Multi-Protocol Networks)

In networks running both OSPF and IS-IS, the Route Path panel includes a protocol toggle ([OSPF] [IS-IS]). The toggle auto-detects which protocols the source device participates in and disables unavailable options (grayed out with a tooltip explaining why). When you change the source device, the toggle automatically switches to a protocol the device supports. Path computation uses only areas belonging to the selected protocol.

IS-IS Address Family Selector

When the selected protocol is IS-IS, the Route Path panel replaces the protocol toggle with an address family selector: [CLNS] [IPv4] [IPv6]. The buttons are dynamic -- each is visible only if the IS-IS instance advertises that protocol capability (TLV 129), and enabled only if actual route data exists in the database for that AF.

CLNS (default for IS-IS): Displays System IDs and full NET addresses per hop instead of Router IDs and interface IPs. The hop table shows: Hop, System ID, Level, Circuit, Cost. The prefix input is hidden (CLNS routing is purely topology-based). When all hops share the same level, the Level column is hidden and a summary line shows the level instead.
IPv4: Standard traceroute with IPv4 interface addresses, same as OSPF.
IPv6: Traceroute with IPv6 interface addresses from TLV 236 prefixes.

L1/L2 transition annotations appear at boundary hops when the path crosses between IS-IS levels.

The endpoint selector adapts to the selected AF: in CLNS mode, the interface IP picker is hidden (devices are identified by System ID only). In IPv4/IPv6 mode, the picker shows the relevant address family's interfaces.

SR-MPLS Label Stack

When viewing an IS-IS IPv4 or IPv6 path to a specific prefix, and the network has SR-MPLS data (Prefix SID, SRGB from TLV 242), the hop table shows an additional Label column. Each hop displays the computed MPLS label for that segment:

Index mode: label = SRGB base + SID index (most common deployment)
Absolute label: used directly when the V-flag is set on the Prefix SID

The Label column auto-hides when no SR-MPLS data is available for the path. SR-MPLS data is extracted from IS-IS TLV 242 (Router Capability), sub-TLV 3 (Prefix SID on TLV 135/236), and sub-TLV 31 (Adjacency SID on TLV 22).

Failed Path Diagnostics

When no path can be found between two devices, the Route Path panel displays a step-by-step explanation of why the path failed instead of just "No path found". The diagnosis covers:

Shared area analysis — whether source and destination share any areas
Backbone reachability — whether both devices can reach the backbone (area 0.0.0.0 or Level 2)
Entry/exit ABR analysis — which ABRs connect each device's areas to the backbone
Area membership mismatches — when devices exist in completely separate areas with no inter-area path

When you ask for a host address, or add a destination address, and no route carries that prefix exactly, Osprey follows the router's longest match: it shows the path for the most specific route it knows that contains the address, marks it longest match next to the prefix and explains this in the first Explain step. A router with a more specific route that Osprey does not observe would forward differently. For EIGRP sources Osprey keeps answering the exact network only. If you ask for a network without an address that no route carries exactly, but a less specific route contains it, the explanation says No exact prefix route and names that covering network instead of claiming that no route exists.

When the selected scope spans multiple protocol instances (e.g. two tenants' OSPF processes, or OSPFv2 and OSPFv3 side by side), the diagnosis counts each instance's backbone separately and tags ABRs with their instance — several healthy, unrelated backbones are never summed into one "disconnected" count.

Forward path failures are shown in orange; reverse path failures in blue.

Cross-Domain Verdict

When source and destination live in different routing domains — a different autonomous system, tenant network, or VRF — no IGP path can exist by design, and the panel says so explicitly instead of walking the ABR checklist. A banner shows both endpoints with their AS and tenant badges, and when Osprey's BGP data (BMP) knows a chain between the two ASes, the banner shows it: 65100 → 65000 → 65200 — see the AS-Flow view.

Two devices that share a routing domain but no protocol instance (for example an OSPFv2-only and an OSPFv3-only device) can still be joined through a device that participates in both instances. Such a path is shown with a caveat: it crosses protocol instances via a shared device, which implies redistribution that the LSDBs cannot verify — treat it as a hypothesis, not a routed fact.

Multi-Domain Paths (BGP-Stitched)

When BGP monitoring (BMP) provides enough evidence, a cross-domain query goes one step further: Osprey combines the IGP segments inside each domain with the observed BGP transitions between them and shows it with a MULTI-DOMAIN badge. Each domain renders as a segment with its own IGP cost (costs are never summed across domains: different metric spaces) and a confidence chip:

resolved — a BGP RIB entry confirms the border router and its next-hop into the next domain.
inferred — only an established eBGP session points toward the next AS; the exact RIB decision is not visible.
opaque — no usable evidence inside that domain: it renders as a cloud with a note (e.g. "exit toward AS 65200 unknown — no session data") instead of guessed hops.

An active MPLS-TE headend adds the note IGP shortest path; TE steering may differ. Tunnel state is live-only, so that annotation is unavailable in Time Travel.

Ordinary live device-to-device and prefix paths also check for known active TE headends, including ECMP alternatives. Their explanation says IGP-derived path; TE steering may differ and names a headend. This indicates possible steering, not proof that traffic uses a tunnel. If the inventory lookup fails, the explanation states that TE steering was not evaluated. No TE note does not establish that a network has no tunnels; discovery coverage still applies.

Historical stitched paths use the BGP history, topology snapshots, and EIGRP samples available at the selected time. Missing EIGRP coverage makes the affected domain opaque. Explanations identify other missing historical evidence, such as SNMP session observations and L2 port details.

Where LLDP/CDP data is available, the transition explains the connection between border routers:

Detail	Interpretation
A single port pair	One visible physical connection between the borders.
Parallel L2 links	Several cables are possible; the session's cable is undetermined.
Shared L2 fabric	Both borders attach to a known switch. That alone does not prove the traffic crosses it.
L2 ambiguous	Both direct and switched connections are possible.
ip-bound	The devices' IP-MIB data ties the session addresses to specific ports. A confirmed switch transit can appear as a hop.
via route server	The deciding route was reported through a route server. The explanation states any uncertainty about its forwarding role.

L2 observations older than six hours carry their age. After thirteen hours they are omitted from the transition detail.

Hops outside the selected canvas scope appear as translucent, dashed ghost placeholders. They keep the path visible through other networks. They disappear when you clear the path, become normal nodes when included in the selected scope, and are not saved in layouts.

When forward and reverse costs are equal, the panel shows whether the routes are congruent (same links in both directions) or different (same cost but traversing different links, highlighted in yellow).

Endpoint Address Selection

Each endpoint (source and destination) in the Route Path panel has a chevron button. Click it to expand an interface address picker showing the device's interfaces grouped into Loopback and Transit / P2P sections. Select a specific interface IP to compute the path to/from that address, or choose Any (device) to use the device itself. When a source address is IPv4, the destination picker filters out IPv6 addresses (and vice versa).

For a live OSPFv2 IPv4 route to a prefix, Osprey can calculate the cost through the network containing the forwarding address. The explanation includes the cost of reaching that network, rather than just the router advertising the external route. This can change which advertisement is preferred.

Read the warning beside the result: these calculations use retained topology data. A withdrawn network can remain in the model until existing updates and cleanup take effect. A matching network does not verify current forwarding. When no usable covering network is available, Osprey keeps the existing route assumption and warns about the uncertainty. This correction does not remove such advertisements. A competing advertisement can also make the route choice uncertain, even when the displayed winner has no forwarding address.

Historical requests keep their existing calculation and can differ from live answers. The routing-table and hop-chain views are not changed by this prefix cost correction. BGP-LS observations without forwarding-address evidence still warn when the model assumes a zero forwarding address. Other observations in the same area can supply an explicit address; those retain their evidence.

Route Explanation

Each direction (forward and reverse) in the Route Path panel includes an Explain button. Clicking it expands a numbered explanation of the routing decision:

OSPF Intra-area (O): Identifies the shared area and SPF cost.
OSPF Inter-area (O IA): Shows the backbone transit path and ABR transitions with per-segment costs.
OSPF External (E1/E2): Explains the LSA type, ASBR, external metric, and forwarding address if applicable.
IS-IS L1 (I L1): Intra-level route within Level 1. Uses I L1 badge and IS-IS hostnames in explanation.
IS-IS L2 (I L2): Intra-level route within Level 2. Uses I L2 badge. Explanation references "level-2 backbone".
IS-IS inter-level (I L2 across two levels): A path that leaves a level-1 area and crosses the level-2 backbone is still labelled I L2 — the level, not the crossing, names the route. The explanation shows the L1/L2 transition and the per-level costs.
IS-IS leaked (I IA): A prefix leaked down into a level-1 area with the up/down bit set (Cisco prints i ia). It gets its own wording — a leaked prefix is not reachable by SPF inside that level, so the explanation names the leak instead of calling it an intra-level route.
ECMP note: When multiple equal-cost paths exist, the explanation notes the count.

The per-router routing table: route counts per type, then one row per prefix with its type badge, metric, next hop, area and advertising router

The routing table (right-click > Show routing table) also supports explanations: click any route row with a triangle indicator to expand inline derivation steps showing how the route's metric was computed. A row that this router advertises itself but is not attached to — an IS-IS Level-1/Level-2 router re-advertises its whole level-1 area in its level-2 LSP — shows no next hop and says so: the real next hop lies in an area outside the selected scope, so the row is the advertisement, not an installed forwarding entry.

SPF Tree

Right-click any device and select SPF tree from here to view the Dijkstra shortest-path tree rooted at that device within its selected OSPF area or IS-IS level.

Single-area devices: Clicking the menu item opens the tree directly.
ABR / multi-area / L1L2 devices: A submenu appears listing each area or level the device belongs to. Select which area's SPF tree to view. In mixed OSPFv2+v3 deployments where the same dotted-quad area exists in both protocols, a suffix disambiguates: "Area 0.0.0.0 (v2)" vs "Area 0.0.0.0 (v3)". For IS-IS L1/L2 routers, the submenu shows "Level 1" and "Level 2".
When viewing a single area in the sidebar: Always opens directly (the area is already determined).

The SPF Tree panel shows:

Element	Description
Header	"SPF Tree" with area label badge, root device name, node count, and max cost
Expand/Collapse	"Expand all" and "Collapse all" controls
Tree rows	Indented tree with CSS connector lines. Each row shows: device name (hostname or router ID), ABR badge (blue), ASBR badge (amber), and collapsed child count hint
Cost columns	Link cost (+N for each hop), total cumulative cost, and a proportional cost bar

Click any device in the tree to highlight it on the canvas. The tree is time-travel aware -- when viewing historical topology, the SPF tree is computed from the historical snapshot.

7. Reports

Access all reports from the Reports menu in the menu bar. The menu is organized into submenus: Inventory, Routing, and Diagnostics, plus top-level entries for Change Summary, Topology Diff, and more.

Report availability follows the areas selected in the sidebar. OSPF-specific reports are disabled for an IS-IS-only selection; focus or hover the menu item for the reason (on touch, hold it). The LSDB Browser also requires recorded database contents and is unavailable for a scope supplied only by BGP-LS. IS-IS neighbors and timers remain available in device and link details.

Most table-based report panels share these common features:

Search: Real-time text filtering across all visible columns. Supports two modes:
- Text mode (default): Case-insensitive substring match. Behaves like a standard search box.
- Regex mode: Click the .* button next to the search input to toggle regex mode (the button highlights when active). Use regular expression patterns for advanced filtering:
  - gw|cr -- match rows containing "gw" OR "cr"
  - ^10\. -- match rows starting with "10."
  - \d{3} -- match rows containing three consecutive digits
  - 0\.0\.0\.0 -- match literal IP address (dots escaped)
- Invalid regex patterns (e.g., [unclosed) show a red border on the input and fall back to literal substring match, so typing is never broken.
- Live route reports support server-side text and regex search. The external-default preset supplies an exact filter and hides the search input.
Column configuration: Click the gear icon to show/hide columns and drag-to-reorder.
Sorting: Click any column header to sort ascending, click again for descending.
CSV export: Download the current (filtered, sorted) view as CSV.
Resizable panel: Drag any edge or corner handle to resize. Minimize to the pill bar to temporarily dismiss without losing scroll position or column configuration.

Column visibility and order persist across sessions via user settings.

Inventory Reports

Routers

Reports > Inventory > Routers

Lists all discovered routers (OSPF and IS-IS). When IS-IS areas are checked, an additional System ID column appears. CSV export filename: routers.csv.

Column	Default Visible	Description
Router ID	Yes	OSPF router ID or IS-IS system ID
System ID	Yes (IS-IS)	IS-IS system ID (XXXX.XXXX.XXXX); shown when IS-IS areas are included
Name	Yes	Display name (per system name mode)
Vendor	Yes	SNMP sysDescr-derived vendor
Model	Yes	Device model
Platform	Yes	Hardware platform
Version	Yes	Software version
Role	Yes	ABR, ASBR, and/or Collector badges
Areas	Yes	OSPF area or IS-IS level memberships
Device Type	Yes	Router, switch, firewall, etc.
First Seen	No	First discovery timestamp
Last Seen	No	Most recent update timestamp

Links

Reports > Inventory > Links

Lists all IGP adjacencies (OSPF and IS-IS). When IS-IS areas are checked, additional System ID columns appear and link type shows "broadcast" instead of "transit". CSV export filename: links.csv.

Column	Default Visible	Description
Source	Yes	Source device display name
Target	Yes	Target device display name
Source IP	Yes	Source interface IP address
Target IP	Yes	Target interface IP address
Cost (fwd)	Yes	Forward IGP cost (OSPF cost or IS-IS metric)
Cost (rev)	Yes	Reverse IGP cost
State	Yes	Link state with color badge (green=up, red=down)
Source RID	No	Source router ID
Target RID	No	Target router ID
Source System ID	No (IS-IS)	Source IS-IS system ID; shown when IS-IS areas are included
Target System ID	No (IS-IS)	Target IS-IS system ID; shown when IS-IS areas are included
Source Interface	No	Source interface name
Target Interface	No	Target interface name
Speed	No	Link speed
Type	No	Link type (P2P, broadcast for IS-IS, transit for OSPF)
Area	No	OSPF area ID or IS-IS level

Interfaces

Reports > Inventory > Interfaces

Lists all router interfaces. When IS-IS areas are checked, additional IS-IS timer columns appear. CSV export filename: interfaces.csv.

Column	Default Visible	Description
Router	Yes	Router ID
Hostname	Yes	Device display name
Interface	Yes	Interface short name (e.g., `Gi0/0/1`)
IP Address	Yes	Interface IPv4 address; dual-stack interfaces stack the IPv6 address beneath it
DNS Name	Yes	Reverse DNS (PTR) for the interface IP
Mask	Yes	Subnet mask; dual-stack interfaces stack the IPv6 prefix length beneath it
Peer	Yes	Peer router ID
Cost	Yes	IGP interface cost/metric
Type	Yes	Link type
Speed	No	Interface speed
Description	No	ifAlias description
Full Name	No	Full interface name (ifDescr)
Hello Int.	No	OSPF hello interval (seconds)
Dead Int.	No	OSPF dead interval (seconds)
Auth Type	No	OSPF authentication type
Net Type	No	OSPF network type
IS-IS Hello	No (IS-IS)	IS-IS hello interval; shown when IS-IS areas are included
IS-IS Hold	No (IS-IS)	IS-IS hold time; shown when IS-IS areas are included
IS-IS Metric	No (IS-IS)	IS-IS interface metric; shown when IS-IS areas are included
Circuit Type	No (IS-IS)	IS-IS circuit type; shown when IS-IS areas are included
Level	No (IS-IS)	IS-IS interface level; shown when IS-IS areas are included
First Seen	No	First discovery timestamp
Last Seen	No	Most recent update timestamp

Software Versions

Reports > Inventory > Software Versions

A specialized report (not a standard table) that groups devices by software attribute for fleet-wide analysis.

Group-by selector: Choose how to group: by Software Version, Vendor, Platform, or Vendor + Version combination.
Summary bar: Shows total device count and number of distinct groups.
Group rows: Each row shows the group name, device count, and a percentage distribution bar. The group with the fewest devices is highlighted with a "rarest" badge.
Expandable rows: Click any group to expand and see the individual devices in that group with their router ID, hostname, and additional details.
Search filter: Filter groups by name.
CSV export: Export the grouped data as software-versions.csv.

CDP/LLDP Neighbors

Reports > Inventory > CDP/LLDP Neighbors

Lists all LLDP and CDP neighbor adjacencies discovered via SNMP across every network your current selection touches — a selection spanning several networks shows all of them, each row labelled with its network. Endpoints without bridge or router capability are excluded.

Summary bar: Total neighbor count, unique remote devices (counted per network — the same hostname in two networks is two devices), "spanning N networks" when the scope crosses network boundaries, LLDP count, CDP count.
Columns: Network, Local Device, Local Port, Remote Device, Remote Port, Mgmt IP, Protocol (LLDP/CDP/LLDP+CDP badge), Capabilities, Chassis ID, Platform, Software Version, First Seen, Last Seen.
Software Version: Extracted from CDP (cdpCacheVersion) or LLDP (lldpRemSysDesc). Long version strings are truncated at "Technical Support:" for readability.
Protocol merging: When both LLDP and CDP discover the same neighbor, the record shows "LLDP+CDP" and combines data from both protocols.
Column configuration: Toggle column visibility, drag to reorder, resize. Settings are persisted in your user profile.
Search: Free-text filter across all visible columns.
Sort: Click any column header to sort ascending/descending.
CSV export: Export visible data as l2-neighbors.csv.
Exclude entries: Each row ends in a crawl toggle. Switching it off hides the neighbor from the report and the L2 canvas overlay and excludes it from SNMP-driven L2 topology views — scoped to that row's own network. The flag persists across discovery cycles — new polls do not reset it. To see excluded entries, check the "Excluded (N)" checkbox in the toolbar and switch the toggle back on to restore them.

Enable L2 Discovery in each network's Enrichment panel to collect these observations.

Routing Reports

LSDB Browser

Reports > Routing > LSDB Browser

A reconstructed view of the OSPF link-state database, in 6 tabs: Router (Type 1), Network (Type 2), Summary (Type 3), ASBR (Type 4), External (Type 5), NSSA (Type 7).

The LSDB Browser on its Router tab: one row per LSA with router ID, hostname, ABR and ASBR flags, link count, age, sequence number and checksum

The External and NSSA tabs also retain stored advertisements excluded from route calculations. Routing check explains an area-type conflict; Area (current) identifies the area and its current classification, including when viewing history. Totally-stub and totally-NSSA classifications are operator declarations here. Other classification sources, and missing collector attribution, are shown as Unknown. Collector identifies the last recorded reporter, not every source that may have reported the advertisement. No exclusion is not proof that a route is usable. Search includes this diagnostic information. The existing per-type limit still applies: narrow the selected area scope when the browser reports truncation. Advertisements discarded before storage cannot be recovered by this view.

The browser is OSPF-only. On an IS-IS-only selection the menu entry is disabled with the tooltip "OSPF only — IS-IS uses LSPs, not LSAs"; IS-IS state you would look for here lives elsewhere: overload/attached flags and per-level membership in the Node Detail Panel, adjacencies and timers in the link details. For automation, GET /api/v1/isis-lsdb returns raw IS-IS LSP headers (sequence number, remaining lifetime, overload/attached bits) — populated only where a GRE IS-IS recorder receives LSPs; it has no browser UI.

Common features:

Summary badges: Each tab header shows a count badge with the number of LSAs of that type.
Expandable rows: Click any LSA row to see its full decoded content.
Search filter: Filter by advertising router, link ID, or content.
Auto-refresh toggle: Enable to automatically refresh the LSDB view every 30 seconds when topology updates occur. A manual Refresh button is also available.

Note: Age, Sequence Number and Checksum are live protocol header fields. They exist only where a GRE recorder received the LSA over a real adjacency (the engine persists them); an LSDB reconstructed from SNMP walks has the LSA contents but no live headers. Where headers exist, the browser shows them as Age / Seq# / Cksum columns, with partial coverage disclosed as a count ("live LSA headers on X of Y shown"); where none exist, the summary bar states "(LSAge, SeqNo, Checksum not available)" instead of rendering zeroes that would look like freshly flooded LSAs.

The browser follows the Time Travel clock: at a historical time, topology and route LSAs reconstruct as of that moment, and the view refetches when you move the clock. Header metadata is not historized — a banner states that age/seq/checksum keep live values.

Neighbor Table

Reports > Routing > Neighbor Table

Shows OSPF adjacencies per device. Also open it from a device's Show neighbors context-menu action. For an IS-IS-only selection, use the Neighbors tab in the device details.

Device selector dropdown: Choose a specific device to view its neighbors, or view all devices.
Summary bar: Shows total neighbor count with up/down breakdown (e.g., "12 neighbors: 11 up, 1 down").
9 displayed columns: Neighbor ID (with ABR/ASBR flag badges), Hostname, State (green/red dot with FULL/DOWN label), Address (local and remote IPs), Interface name, Cost (single value for symmetric, with forward/reverse arrows for asymmetric costs), Type (P2P, broadcast), Area, Last Seen.
CSV export: Exports 14 columns (including additional fields) as neighbors.csv.

IGP Prefixes

Reports > Routing > IGP Prefixes

Lists stub networks from the IGP LSDB (OSPF connected subnets and IS-IS IP reachability prefixes). This report is IGP-only — for BGP prefixes/routes, use the BGP Routes report. CSV export filename: prefixes.csv.

Columns: Network, Cost, Router, Area, First Seen, Last Seen.

The header shows both the row count and the number of unique prefixes when they differ. A prefix can appear in several areas' databases. For example, an IS-IS Level 2 database can also carry prefixes learned from Level 1. Use the Area column to identify each observation's source.

Inter-Area Routes

Reports > Routing > Inter-Area Routes

Shows Type 3 LSA summary routes learned via ABRs. CSV export filename: inter-area-routes.csv.

Columns: Network, Metric, Advertising Router, Router, First Seen, Last Seen.

External Routes

Reports > Routing > External Routes

The exclusion notice counts stored advertisements excluded by the current area type across the whole selected scope, before search or prefix filtering. Those advertisements are not included in the route or group totals. For their retained evidence, open Reports > Routing > LSDB Browser > External using the same scope and time. An unavailable count is not zero. Historical results use the current area classification. Isolation-impact details in Dependency Analysis similarly disclose the excluded advertisements of isolated devices.

Shows stored Type 5/7 external advertisements, grouped by process, prefix, metric type and LSA type. Type 5 uses E1/E2; Type 7 uses N1/N2. Advertisers counts distinct stored devices within each group. Process identifies the network, AS, routing domain, protocol, process and address family. An NSSA original and translation can have different advertisers; counts do not establish independent origins.

Choose View > External OSPF defaults for exactly 0.0.0.0/0 and ::/0 in the selected scope. This is a stored-observation report, without a completeness or freshness claim, even when rows are present. Advertisements from unknown originators are not stored. SNMP external changes may only appear at the hourly refresh; a stopped area can retain old rows indefinitely.

Click a prefix for all its types/processes in scope, with router names and per-area rows. Record Since is when that area record was first stored; it resets when the advertisement disappears from snapshots for a while. The summary shows the earliest current record start. Last Seen is visible by default in the preset; the summary's Newest Last Seen is the newest contributing row, not proof that every row is current. Timestamps are UTC, not configuration history.

Page/sort refresh retains the previous rows with Updating status and disables navigation/CSV until completion. CSV exports the loaded page and visible columns as external-ospf-defaults.csv (external-routes.csv for the ordinary view). Stable sort tie-breakers do not freeze changing data between page requests. Entering Time Travel exits the preset; returning to live keeps All external routes until the user explicitly selects the preset again.

Stub-area summary defaults, IS-IS defaults, default history and per-router route-choice impact are outside this preset. Type-5 rows in known stub/NSSA areas, including totally variants, are excluded from the two report readers. No acquisition or route-computation behavior is changed by this view.

BGP Peers

Reports > Routing > BGP Peers

Lists BGP peers discovered from either BMP or SNMP BGP4-MIB walks. BMP targets can be configured from the BGP instance in the sidebar or through the API; see Setting Up BGP Monitoring. SNMP-discovered peers provide session state and the fields exposed by the MIB, but no RIB visibility; route and per-peer candidate history require BMP.

Column	Description
Peer IP	Remote BGP peer IP address
AS	Remote peer ASN
Type	Internal (iBGP) or external (eBGP)
AF	Address family (IPv4 / IPv6)
State	Peer state with colored dot (green = established, red = down)
Prefixes	Number of prefixes received from this peer
Rejected 24h	The router's own inbound-policy reject counter with a 24-hour trend sparkline. Comes from BMP Statistics Reports; a "—" means the router does not send them (on Cisco IOS, configure `stats-reporting-period` under the BMP server) — it never means "nothing rejected"
Path t½	Median lifetime of the candidate paths this peer offered in the last 24 hours (requires a full-RIB history target; the tooltip carries the p90 and cohort counts)
Churn shape	Most common type of candidate-path change over 24 hours, with its share. Hover for the breakdown and busiest prefixes. Requires full-RIB history.
Router ID	Peer's BGP router ID
Last Seen	Most recent update from this peer

Churn shape describes what changed:

Selection flips: Attributes stayed the same but the selected path changed. With inferred selection, this describes Osprey's recomputation; with Loc-RIB, it reflects the router's choice.
Next-hop only: The next hop changed while the AS path stayed the same.
Path hunting: The AS path changed while the origin stayed the same.
Cosmetic: Only MED or communities changed. This category describes the fields; it does not establish that the change was operationally harmless.
Announcements / withdrawals: Candidate paths appeared or disappeared.

Changes faster than the feed or recording interval can be missed. Rebuilding a history baseline is not counted as a new announcement. Hot prefixes are the prefixes responsible for the most recorded changes.

Fields that require BMP Statistics Reports or full-RIB history show an explicit dash/reason when the peer was discovered only through SNMP; absence is never rendered as a measured zero.

Search: Free-text filter across all columns.
Pagination: Server-side, with configurable page size.
CSV export: Download filtered data as bgp-peers.csv.
What-if: the ⋯ menu on a peer row estimates the effect of a peer failure — how many prefixes currently ride this peer, how many would become unreachable, and how many peers survive. Deeper multi-mutation scenarios live in the Simulation panel.

BGP Routes

Reports > Routing > BGP Routes

Searches BGP best paths received through BMP. The Source column distinguishes the router's Loc-RIB from Osprey's inferred selection. Supports three prefix match modes for flexible route analysis.

Match modes (selector next to the search field):
- Exact: Returns only the prefix that exactly matches your search (e.g., 10.0.0.0/24 returns only 10.0.0.0/24).
- Longest match: Returns the most specific (longest prefix length) matching entry, like a router's forwarding table lookup.
- Covered: Returns all prefixes that fall within the searched prefix (e.g., 10.0.0.0/8 returns 10.0.0.0/24, 10.1.0.0/16, etc.).

Column	Description
Prefix	BGP route prefix (CIDR notation)
On router	The selecting router — every BMP-monitored router computes its own best path, so the same prefix appears once per router. Essential with redundant route reflectors, which can legitimately pick different winners
Next Hop	BGP next-hop IP address
AS Path	Full AS path string
Origin AS	Originating ASN
LOCAL_PREF	BGP local preference value
MED	Multi-Exit Discriminator
Source	How the best path was determined: `loc_rib` (from router's own LocRIB via BMP) or `inferred` (engine-computed best-path selection)
ECMP	Equal-cost multipath count -- the number of next-hops that tied across all 6 best-path comparison steps
Updated	Timestamp of last best-path change

Pagination: Server-side with offset capped at 100,000 to prevent slow queries on large RIBs. Use prefix/AS filters to narrow results.
CSV export: Download filtered data as bgp-routes.csv.

ECMP: A count above 1 means multiple next hops tie under Osprey's BGP comparison rules. It does not confirm that the router installed every tied path or that traffic is evenly balanced. Check the source and the router's multipath policy.

Per-Peer Received Paths

Expand Show N paths on a route to compare the candidates received by its selecting router. Each row identifies the peer, next hop, AS path, origin, LOCAL_PREF, MED, IGP metric, and communities. BEST marks the selected path.

If a ROA set has been imported, paths with a known origin also show:

Badge	Meaning
valid	A covering authorization permits this origin and prefix length.
invalid	Covering authorizations exist, but none permits this origin and length.
roa?	No covering authorization was found.

No badge is shown when no ROA set is loaded.

The expansion follows the time-travel clock. At a historical time it serves the candidates recorded then, which requires a BMP target recording full history (history_mode: "full") for the AS — without it no candidates were recorded at that time, the path count reads 0 and rows offer no expansion.

BGP Change Replay

Hover a route row and click the ↺ replay button to open the change replay for that prefix — a focused view of how that one route changed over time. It requires BGP history recording (a BMP target with a history mode other than off — see the target's settings), and it works on the same timeline as Time Travel: there is no second clock. The window opens as a fixed span (±12 hours) around the moment you were looking at.

Event strip: a density band across the window — announcements and attribute changes above the line, withdrawals below, with small ticks for peer session changes. A vertical line marks the current time; click anywhere on the strip to jump the whole app's clock to that instant.
Event table: every change in time order, showing the old → new next-hop and AS-path side by side. The row for the current time is highlighted. Click a row (or use the ◀ / ▶ buttons) to step to that change. Reconciliation entries (recorded when monitoring resumes) are labelled and can be hidden; a busy window that exceeds the display cap shows a banner asking you to narrow the range.
On the map: while the replay is open, the followed prefix's exit is drawn on the topology canvas as an animated dashed line from the router holding the route to its next-hop router, with everything else dimmed. Routers whose BGP session flaps at the cursor time pulse briefly.
Compare: click Compare to pin the current time as T1, then scrub the timeline — the view lists exactly what changed between T1 and where you scrub to (paths added, removed, or with new attributes). Useful for confirming "what did this maintenance window actually change".
Candidate paths (full mode only): if the BMP target records full history (all received paths, not just the winner), a panel lists every candidate path from each peer at the cursor time, with the selected best one marked — so you can see why the best path changed (for example, the previous best peer withdrew, or a higher-local-preference path arrived). On best-path-only targets this panel shows a short "requires full mode" note instead. Candidate lanes carry the ROA badge too, validated against the authorizations that were loaded when that candidate appeared — updating your ROA set never rewrites what an old candidate was.

Importing a ROA Set

An administrator or engineer can import route-origin authorizations through the API. Use JSON with a roas array. Each entry has asn, prefix, and optional maxLength fields, for example {"roas":[{"asn":64500,"prefix":"192.0.2.0/24","maxLength":24}]}. Each source label identifies a separate snapshot; importing that source again replaces its previous contents.

curl --fail-with-body --cacert /path/to/osprey-ca.crt \
  -X POST -H "X-API-Key: <key>" \
  -H "Content-Type: application/json" \
  --data-binary @roa.json \
  "https://osprey.example.com/api/v1/bgp/roa/import?as_id=<uuid>&source=registry"

Use a trusted CA certificate for your installation; omit --cacert if your system already trusts it. The ROA summary is available at GET /api/v1/bgp/roa/summary.

No invalid candidates does not prove that all routes are valid. An upstream or route server may filter invalid routes before they reach the monitored session. Read the per-session coverage information alongside the badges.

BGP AS Flow

Reports > Routing > BGP AS Flow

AS Flow shows which autonomous systems appear in your observed BGP paths and how their shares change over time. It measures routing entries, not traffic volume. A large bubble means a large share of the selected paths passes through that AS.

Start here:

Select an AS with a BMP target that records history.
Choose Best paths or All candidates under Paths.
Choose Columns or Radial for the layout.
Click an AS for details, or move the timeline to inspect an earlier state.

Columns arranges ASes from left to right by hop distance. Radial places your AS in the center, with one ring per hop; the outer ring groups distances of five or more hops.

Distance means hop distance over observed adjacencies. It is not a per-route minimum. The main tree groups an AS under its heaviest observed upstream. Dashed connections show other relationships that do not fit in that tree. Two neighboring ASes in an AS path do not necessarily have a direct BGP session; a transparent route server can sit between them.

Zoom and pan: Use the mouse wheel or +/− to zoom; drag to pan. Press 0, click Fit, or double-click the background to fit the graph.
More detail: Zooming in reveals labels and counts. In Radial, it also reveals folded origins when there is room.
Find: Click ⌕ Find and enter AS numbers to keep them visible regardless of ranking.
AS numbers: Clear this checkbox to reduce label clutter. Your AS, the selected AS, and other keep their labels; hover another bubble for its identity.
Maximize: Expand the panel to use the available canvas space.

Changing AS, layout, ranking, path source, fold threshold, or center resets the camera. Moving the timeline keeps the camera in place.

AS Flow path selection and ranking

Control	Use it to
Paths: Best paths	Inspect the selected routes. Check whether selection comes from Loc-RIB or is inferred by Osprey.
Paths: All candidates	Inspect every offered path, including alternatives. Historical candidates require full history.
Rank by: Origins	Name the origins with the most routing entries.
Rank by: Transit spine	Highlight the ASes through which much of this feed is reached. Another observation point can produce a different spine.
Rank by: Address space	Rank indirectly reached origins by unique IPv4 address space. Overlapping prefixes count once. This measures address coverage, not whether a network is a suitable peering partner.
Fold beyond / Name top N	Choose how many origins remain individually named; the default is 12. Other origins are grouped under ⬡ other. Transit ASes remain visible.

The header states the counting unit. Candidate entries count a prefix separately for each router and peer path, so their totals can exceed best-path totals. candidates ≡ best means the feed supplies only best paths.

In Radial, each branch can have its own amber other arc. Click it to inspect the anchor AS, then choose ⌖ AS flow from here to explore that branch. Use Back to return. This remains your observation of those paths, not that AS's own routing view.

Named origins are chosen at the start of the time window, so playback does not continually rename the graph. An origin can appear in more than one folded branch; do not add branch origin or address-space counts to get a unique total.

AS Flow timeline and comparison

The timeline covers a window around the selected time. Announcements and changes appear above its baseline, withdrawals below, and session flaps as diamonds.

Play animates changes and slows through busy periods. Step buttons move to the previous or next change.
+N/−N badges identify affected ASes. Hover a badge for its counting unit; a summary below the graph describes the change.
Diff pins the current time as T1. Move the cursor to compare T1 with T2. The comparison lists rerouted, announced, and withdrawn prefixes. Sample prefixes open BGP Change Replay.
In comparison mode, green flows gained share and red flows lost share.

In Best paths mode, a dashed presence strip along a flow shows when that adjacency appeared in recorded paths across the window. Gaps indicate periods without recorded presence. Hover for the bucket count. Candidate paths and folded groups do not carry this strip.

Read the coverage line before interpreting a quiet timeline. It shows observed session time, monitoring gaps, new history baselines, and periods when high volume suppressed recording. Missing observations do not establish routing stability.

AS Flow details

Click a bubble to open its AS dossier:

Detail	Meaning
Share trend and churn	How this AS's share changed; routes gained, lost, or rerouted.
Shadow share	Prefixes for which this AS is the only offered path or provides a backup. Requires full history.
Path half-life	Median and p90 candidate-path lifetime. If many paths are still present, the displayed value may be a lower bound. Requires full history.
Prefixes and exit routers	Open a prefix's replay or locate its exit on the topology canvas.
Session health	Available observations of your sessions to the AS.
Transit details	Observed upstreams, the AS's own origins, deaggregation, and transit reach. Unique IPv4 reach counts overlapping address space once.

Click a flow line to see its two ASes, entry count, and each side's share. At the live time, the card also explains why paths win here: the deciding BGP comparison step and median winning margin. Only path offered means there was no alternative. Undetermined means Osprey could not reconcile the comparison with the stored selection. Historical views do not substitute this live explanation.

The shape row summarizes origins, named share, transit-spine coverage, paths outside the main tree, and paths at five or more hops. Use these figures to understand how much detail the visible graph groups together.

AS Flow requires a BMP target with history recording enabled. Historical All candidates, shadow share, and candidate lifetime analysis require full history.

BGP Security

Reports > Routing > BGP Security

This report checks the candidate paths offered on your monitored BGP sessions. Select an AS with an enabled BMP target. The panel shows live findings; the API can also query historical candidates when full history covers the requested time.

Multiple origins offered: a prefix open with two or more distinct origin ASes across your sessions, each origin with the sessions that offered it. Legitimate anycast and misconfiguration look identical from one vantage — the report states the offers and stops there.
More-specifics under another origin's cover: a candidate open for a prefix while a covering prefix with a different origin is open — the classic shape of both traffic engineering and interception.
Paths already containing your AS: A peer offered an AS path containing your own ASN. Investigate the peer and the router's loop-prevention policy. The observation alone does not establish which policy the router applied. RFC 4271, section 9.1.2, describes the normal loop check and leaves configurations accepting their own ASN outside its scope.

Each finding identifies a path offered on a named session at a particular time. It does not establish that the router accepted it or that it was malicious. Anycast, traffic engineering, and configuration mistakes can produce similar patterns.

If candidate data does not cover the selected scope, the report displays the reason. An empty result under that warning is not an all-clear. Lists also indicate when a display limit has truncated them.

BGP-LS Panel

Reports > Routing > BGP-LS...

Inspect the nodes, links, and prefixes received from BGP-LS exporters. Use the Links, Nodes, and Prefixes tabs to browse objects. The Sources tab lists BMP sources and direct peers; engineers and administrators can add, edit, pause, or delete direct peers there.

Label	Meaning
Reporter chip	Lists the exporters that reported the object. Identical objects appear once. Agreement between exporters relaying the same database is not independent confirmation.
withheld	The object arrived without its BGP-LS attribute. Required details, such as link metrics, are unavailable.
attr discarded	A malformed attribute was discarded. Check the exporter.
pseudonode	Represents a broadcast segment, rather than a router.
stale	The reporting session is down. This is a monitoring gap, not a route withdrawal.
refusal	Osprey cannot safely use this source's topology. The panel names the reason, such as an object budget or lost input.

An empty panel distinguishes no source configured from nothing received. If a source is configured, check the router's link-state export and address family. For BMP sources, also check that BMP mirrors the BGP-LS session. See BGP-LS setup.

MPLS-TE Tunnels

Reports > Routing > MPLS-TE Tunnels

Use this panel to inspect discovered traffic-engineering tunnels and locate their endpoints. It requires MPLS discovery through SNMP. The menu entry appears when tunnels have been discovered.

Select the relevant network and areas in the sidebar.
Open the report and check each tunnel's head, transit, or tail role, administrative state, operational state, and signalling protocol.
Select a tunnel to draw its head-to-tail arc on the canvas. An active arc is animated; a down tunnel uses a broken red line.

The arc identifies the tunnel endpoints. It does not establish the complete hop-by-hop route through the core. If an endpoint is outside the visible topology, check the selected areas and the endpoint's discovery coverage. The overlay is available in live mode only.

L3VPNs

Reports > Routing > L3VPNs

Use this panel to find which provider-edge (PE) routers participate in a discovered Layer 3 VPN. It requires MPLS discovery and router support for the VRF MIB tables.

Select a VPN to inspect its sites and highlight them on the canvas. Osprey groups VRFs by their route-target relationships. A full-mesh VPN draws membership connections between sites; a hub-and-spoke VPN draws them from the hub.

These connections describe VPN membership, not the forwarding path through the core. A site marked off-view is outside the displayed topology; that label alone does not mean it is down. Per-VRF route counts are shown only when the router supplies its VRF performance table. A missing route total does not mean the VRF has no routes.

If no VPNs appear, check MPLS discovery, SNMP access to the PEs, and the MIBs those routers expose. The canvas overlay is live-only.

VPWS Wires

Reports > Routing > VPWS Wires

Use this panel to inspect point-to-point pseudowires. It requires MPLS discovery and pseudowire information from the endpoint routers.

Select a wire to inspect its endpoint PEs, VC ID, attachment circuits, per-end status, and signalling label: LDP, static, or EVPN. When both endpoints can be placed, the canvas draws an arc between them.

A half-wire means Osprey has not identified the far-end PE. The known peer address remains visible, but there is no complete endpoint arc. Check discovery of that peer before treating the missing half as a failed service. A known endpoint outside the selected areas may also be marked off-view.

The arc describes the wire's endpoints and reported status; it does not trace its path through the provider network. The overlay is hidden in Time Travel.

VPLS Instances

Reports > Routing > VPLS Instances

Use this panel to inspect the members of a multipoint Layer 2 VPN. It requires MPLS discovery and pseudowire information from the participating PEs.

Select an instance to see its member PEs, per-site pseudowire counts, and membership connections on the canvas. Read the mesh badge alongside the members:

Badge	Meaning
Full	The observed pseudowires establish a complete mesh among the discovered members
Partial	The observed mesh is incomplete
Membership unknown	There is not enough information to establish mesh completeness

Partial or unknown membership needs investigation of both service state and monitoring coverage. Check SNMP access to every expected PE and whether sites are outside the current view. Osprey does not infer a hub-and-spoke design from an incomplete mesh. Membership lines are live-only and do not trace packet forwarding.

EVPN Instances

Reports > Routing > EVPN

The EVPN browser groups observed routes into EVPN instances (EVIs) by their route-target relationships. Reports from redundant route reflectors are combined, and each PE is counted once per instance. Each row shows:

Service kind -- E-LAN (multipoint, discovered from IMET routes) or EVPN-VPWS (point-to-point, from per-EVI Ethernet A-D routes)
Encapsulation -- VXLAN or MPLS, from the route's tunnel-encapsulation attribute
Members and MACs -- how many PEs participate, and the total MAC count across them

Click an EVI to see its member PEs, VTEP or PE addresses, VNIs or labels, and per-PE MAC/IP counts. The panel also shows multihomed Ethernet Segments and recent MAC-move or PE-loss events. It provides aggregate counts rather than a per-MAC table. On-map and off-view indicate whether a PE is in the current canvas scope.

Selecting an EVI highlights its visible PEs and draws membership connections. These connections show control-plane VPN membership from BGP routes; they do not trace packet forwarding through the fabric.

Two symptom events feed the incident system from this data:

evpn_mac_move -- a host moved between PEs, detected via the RFC 7432 MAC-Mobility sequence. All-active multihoming is understood: a MAC advertised by several PEs on the same Ethernet Segment is aliasing, never a move. A per-MAC debounce and a per-target hourly ceiling keep a broadcast storm from becoming an event flood.
evpn_pe_lost -- a PE dropped out of an EVI, fired only when no live BMP feed still sees the membership. A BMP session going down is a monitoring gap, never treated as a withdrawal.

These events can be attached to a related device or link incident. They do not open an incident on their own, and correlation is not proof of the underlying cause.

If a BMP target disconnects, its EVPN observations are flagged stale and the panel says so -- Osprey never presents last-known state as live.

EIGRP Topology

Reports > Routing > EIGRP Topology -- appears only on networks with a discovered EIGRP instance.

The EIGRP topology view combines neighbor observations from individual routers. Each resolved physical adjacency appears once. Bidirectional means both ends reported each other; half means only one side is known.

For one router's neighbors, right-click it and choose EIGRP topology from here. This replaces SPF tree from here for EIGRP, which uses DUAL rather than an SPF tree. The action is available in both scoped and global topology views.

Diagnostic Reports

Topology Health

Reports > Diagnostics > Topology Health

Checks the displayed topology for issues. Results are grouped into 5 categories, each collapsible:

Down Links (error severity): Links in a non-operational state.
Asymmetric Costs (warning severity): Links where forward and reverse IGP costs differ.
Isolated Devices (error severity): Routers with no active adjacencies (excludes recorder nodes).
Single-Homed Routers (info severity): Devices with only one link (potential SPOFs).
ABR Anomalies (warning severity): ABRs with unexpected area memberships.

A summary bar at the top shows error/warning/info counts. Each finding is clickable -- selecting it highlights the affected device or link on the canvas. Device names respect the system-wide Device Name Format setting (Admin > System Settings > Display) -- showing hostnames, DNS names, router IDs, or hostname+IP depending on your configuration. CSV export filename: topology-diagnostics.csv.

IP Conflicts

Reports > Diagnostics > IP Conflicts

Detects four categories of IP address conflicts, displayed in tabs:

Duplicate Router IDs: Multiple devices using the same OSPF router ID or IS-IS system ID.
Duplicate IPs: Multiple interfaces on different devices with the same IP address.
Duplicate Prefixes: The same stub network advertised by 3+ devices (normal for 2 on point-to-point links).
External Conflicts: External routes for the same prefix with different metrics or types from different ASBRs.

Each tab shows severity badges (critical, warning). Click any finding to highlight it on the canvas. Device names respect the system-wide display name mode setting. CSV export filename: ip-conflicts.csv.

Dependency Impact

Reports > Diagnostics > Dependency Impact

Use this report to estimate how a peer, device, link group, or pair of devices affects reachability.

Tab	What it shows
Peer AS	Prefixes and unique IPv4 address space reached through each peer AS, plus the share with no offered alternative. Overlapping address space counts once. Requires BMP data.
Critical Pairs	Device pairs whose simultaneous failure would partition the topology. Expand a pair to inspect the affected devices and links.
SRLG / Devices	The estimated effect of failing a shared risk link group or individual device. Filter by groups, devices, or both.

Expand a row for its affected prefixes, alternatives, or disconnected segments.

Peer AS history. Choose a Scorecard window from 6 hours to 7 days; the default is 24 hours. These columns supplement the live reachability figures:

Column	Meaning
Flaps	Recorded session state transitions, excluding history re-baselines.
Uptime	Recorded uptime, weighted by the observed time of each session.
Churn share	This AS's share of recorded candidate-path changes. Requires full history.
Path t½	Median offered-path lifetime. ≥ means it is a lower bound because many paths are still present.

Hover a dash for the reason a value is unavailable. It is not a measured zero.

The Sessions block includes recorded sessions that are currently down. It shows their flaps, uptime, churn, and last table-dump duration and route count. The coverage line identifies missing observations and suppressed recording. A quiet period during a BMP outage does not establish stability.

Single Points of Failure

Reports > Diagnostics > Single Points of Failure

Identifies network reliability risks using graph theory, displayed in 2 tabs:

Articulation Points: Devices whose failure would partition the network. Shows how many disconnected segments would result.
Bridge Links: Links whose failure would partition the network.

The Single Points of Failure report: how many devices and links were analysed, then the articulation points with the number of components each would leave behind

Severity levels: critical (red) for high-impact SPOFs affecting 3+ segments, warning (yellow) for lower impact (2 segments). Results are sorted by impact descending. Click any finding to highlight it on the canvas. Device names respect the system-wide display name mode setting. CSV export filename: spof-report.csv.

Routing Stability

Reports > Diagnostics > Routing Stability

Analyzes topology event patterns to identify flapping links, unstable devices, and area-level instability. Displayed in 3 tabs:

Flapping Links: Links with frequent state changes. Severity-coded by transition count: critical (10+ transitions, red), warning (5-9, yellow), info (2-4, blue).
Unstable Routers: Devices with high event counts. Severity: critical (50+ events), warning (20-49), info (fewer than 20).
Area Scores: Per-area instability scoring based on event density. Each area receives a numeric stability score derived from the total event count relative to the number of devices and links in that area. Higher scores indicate more volatile areas that may warrant investigation. Areas are sorted by score descending.

Period selector: 1 hour, 6 hours, 24 hours, or 7 days. CSV export filename: stability-report.csv.

Congestion Trend

Reports > Diagnostics > Congestion Trend

Identifies interfaces with sustained high utilization over configurable periods. Requires SNMP targets configured and hourly utilization bucketing data.

Period selector: 24 hours, 7 days, or 30 days.
Threshold selector: 60%, 70%, 80%, or 90% utilization.

Column	Description
Device	Device display name
Interface	Interface name
Speed	Interface speed
Max %	Peak utilization in the period
Avg %	Average utilization in the period
Hours Above	Hours above the selected threshold
Trend	Direction indicator (increasing, stable, or decreasing)
History	Inline sparkline chart showing utilization over time

CSV export filename: congestion-trend.csv.

Timer Consistency

Reports > Diagnostics > Timer Consistency

Checks OSPF timer and configuration differences across link endpoints. It requires SNMP interface data. The Reports menu disables it for an IS-IS-only selection; inspect IS-IS timers in the Link Detail Panel.

Summary bar: Shows total endpoints checked and mismatch count.
Mismatches table with 5 columns: Parameter (with severity badge), Side A (device name), Value A, Side B (device name), Value B.

Severity levels:

Critical: OSPF hello interval, dead interval, or authentication type mismatches that can prevent adjacency formation.
Warning: Network type differences. Check both interface configurations.

For IS-IS, compare hello, hold-time, and metric information in the link details. This OSPF report does not evaluate IS-IS timers.

Click any finding to highlight the affected link on the canvas. CSV export filename: timer-consistency.csv.

MTU Mismatch

Reports > Diagnostics > MTU Mismatch

Detects MTU mismatches between interfaces on opposite ends of a link. Requires the SNMP poller to have walked IF-MIB ifMtu (.1.3.6.1.2.1.2.2.1.4), which is collected during the per-network interface-discovery interval (default 6 hours, configurable in the network's Enrichment panel).

Summary bar: Shows count of mismatched links.
Mismatches table with 4 columns: Side A (device + interface + IP), MTU A, Side B, MTU B.
Click any row to highlight the affected link on the canvas.
CSV export filename: mtu-mismatch-report.csv.

MTU mismatches are common on links between routers using different default MTUs (e.g., jumbo frames on one side, 1500 on the other). While OSPF uses interface MTU from the DBD exchange to detect this at adjacency formation, the MTU Mismatch report provides a topology-wide overview without requiring a GRE recorder.

The MTU value also appears in the Link Detail Panel OSPF Configuration section and as a hidden column in Reports > Inventory > Interfaces (toggle via column picker).

Best Practices

Reports > Diagnostics > Best Practices

OSPF-only. Audits the topology for compliance with OSPF design best practices. Findings are grouped into categories:

Backbone Design: Checks for non-contiguous backbone (area 0), ABRs not connected to area 0, etc.
Stub Compliance: Verifies stub and NSSA area configurations.
Router ID: Detects non-loopback router IDs and duplicate router IDs.
Passive Interfaces: Flags stub networks on non-passive interfaces.

Each finding has a severity level (critical, warning, info) and lists the affected devices. Click any device to highlight it on the canvas. CSV export filename: best-practices.csv.

Note: IS-IS best practices checks are not yet available. When only IS-IS areas are selected, this report is disabled.

Change Summary

Reports > Change Summary

Shows a summary of recent topology changes with visual distribution analysis.

Period selector: 1 hour, 6 hours, 24 hours, 7 days, or 30 days.
Summary cards: Device changes (added/removed/changed counts), Link changes, and Stub Network changes with color-coded badges.
Distribution chart: Visual breakdown of change types over the selected period.
Other Events section: Lists topology events that don't fall into the device/link/stub categories.

Topology Diff

Reports > Topology Diff

Compare topology at two points in time:

Set the From and To timestamps using datetime pickers (defaults to last 24 hours).
Click Compare.
Results show in 3 tabs: Devices, Links, Stub Networks.
Each entry shows whether it was added (green), removed (red), or changed (amber) with summary badges per tab.
Click any entry to highlight it on the canvas.

CSV export filename: topology-diff.csv. Useful for change review, maintenance window validation, and troubleshooting.

8. Tools

Search (Ctrl+K)

Tools > Search or press Ctrl+K / Cmd+K.

Opens a search dialog for quickly locating any device or interface. Type to search across:

Router ID, Hostname, DNS Name, Label, Vendor (device fields)
Interface name, IP address, interface description (interface fields)
CIDR subnet containment (e.g., entering 192.168.1.0/24 finds all interfaces in that subnet)

Results are grouped into Devices and Interfaces sections with match highlighting. Use arrow keys to navigate results, Enter to select. The selected device is highlighted on the canvas and its Node Detail Panel opens.

Time Travel

Tools > Time Travel, or click the clock button in the bottom bar's mode cluster.

View the network topology at any historical point:

Activate Time Travel to show the time scrubber bar at the bottom of the screen.
The bar has transport controls: skip backward/forward, step, play/pause.
Adjust playback speed (0.5x to 10x) and the time window (1h–30d or a custom range).
Drag the scrubber slider to any point in time.
The topology canvas reconstructs the historical state from snapshots.
A blue tint and TIME TRAVEL label on the bar indicate you're viewing historical data (amber = simulation).
Click the green Go Live button to return to real-time.

The Time Travel bar: transport controls, playback speed, time-window buttons, the snapshot scrubber with one dot per snapshot, the selected timestamp and the Go Live button

Keyboard shortcuts while in Time Travel mode: Space (play/pause), Left arrow (step backward), Right arrow (step forward).

Osprey records topology snapshots per area. EIGRP forwarding history is recorded per router. Complete, unchanged polls extend the recorded coverage without creating duplicate route snapshots.

When time travel is active, the Node Detail Panel and Link Detail Panel adapt automatically:

An amber banner shows "Viewing at [timestamp]" at the top.
Critical state banners (device down / link down) reflect the historical topology state at the playback timestamp.
Live traffic polling and boost are suppressed.
The Events section filters to ±1 hour around the playback timestamp.
Utilization charts show a vertical highlight marker at the playback time.

History coverage and limits:

Utilization coloring switches off. View > Color > By Utilization drops its colors at a historical time — the canvas deliberately does not paint today's traffic onto yesterday's topology. Blank means not available at this time, not no traffic. Per-link utilization history is still available in the Link Detail Panel's charts, with the playback marker.
LSA header metadata stays live. The LSDB browser reconstructs LSAs and routes as of the selected time, but age/sequence/checksum have no history; a banner in the browser says they keep live values.
EIGRP history is sampled. The path and routing-table panels distinguish an exact sample, equal observations before and after the selected time, and an earlier sample still within its freshness period. Missing router data makes the affected direction or segment partial or unavailable. An observed empty table and missing coverage are different results. Optional ECMP branches can have less coverage than the primary path.

Combining Time Travel and Simulation: Click the clock in Simulation, or the gear in Time Travel. Your selected time is preserved. A combined bar shows both mode labels, and moving through history reapplies the simulated changes to each snapshot.

Go Live exits both modes. Its dropdown also offers Exit Time Travel to keep simulating, or Exit Simulation to keep viewing history.

For EIGRP simulations, each surviving path retains its own sample time and coverage. Promoting a recorded ECMP alternative does not make it a fresh observation. The explanation identifies it as an installed alternative from the selected historical sample.

Refresh DNS

Tools > Refresh DNS (admin or engineer; hidden for other roles)

Forces a full re-resolution of all PTR (reverse DNS) records for device router IDs and interface IP addresses. Use this when:

DNS records have been updated (renumbering, device replacement)
New PTR records have been added
You want to sync DNS names after zone changes

The refresh happens asynchronously -- the engine clears its DNS cache and re-resolves all cached IPs. Results appear within seconds.

Simulation (What-If Engineering)

Tools > Simulation, or click the gear button in the bottom bar's mode cluster (next to the Time Travel clock).

Simulation lets you test failures, cost changes, hypothetical links, and shared risk link group (SRLG) failures against the discovered topology. It does not change router configuration or the live topology.

OSPF and IS-IS results use shortest-path calculations over the changed model. EIGRP results use the observed primary and installed alternatives where available; they do not predict a new DUAL calculation. Treat traffic redistribution and path changes as model results when planning maintenance.

Entering simulation mode:

When activated, the canvas displays an amber overlay border and a "SIMULATION" watermark to clearly distinguish the simulated view from the live topology. The bottom bar is replaced by the amber simulation bar: SIMULATION label, Baseline/Simulated view toggle, Undo/Redo, a Time Travel entry (clock), the loaded scenario name with mutation count and SPF compute time, the system status cluster, and Go Live to exit. Mutations, impact analysis, paths, batch assessment, and scenarios live in the simulation panel (opens automatically).

Tip: Simulation and Time Travel can be used simultaneously. Click the clock icon in the simulation bar to activate time-travel, or enter Simulation while already viewing historical topology. Simulation results automatically recompute as you advance through snapshots during playback.

Simulating failures and cost changes:

Right-click a link and select Simulate Failure to take the link down in the simulation, or Change Cost... to edit that edge's OSPF cost.
Right-click a node and select Simulate Node Failure to take the device and all its links down.

BGP peer failure:

Right-click a device and select Simulate BGP peer failure... to open the peer picker pre-filtered to that device's own BGP sessions, or click B Peer Failure in the Mutations tab action bar to pick from every peer in scope.
Peers are grouped by AS number with select-all per group, a search box, and impact badges giving an at-a-glance affected-prefix count per peer.
Select one or more peers to add them as mutations; the simulation treats each as a downed BGP session. The peer list itself is time-travel aware (fetched as of the selected time), but impact badges are live-only and hidden during time travel -- the impact-summary endpoint has no historical mode.
Include BGP checkbox (next to the peer-failure button): when enabled, simulations also model BGP hot-potato routing and traffic redistribution effects on top of the IGP-only impact.

Hypothetical routers:

Right-click empty canvas space and select Add Hypothetical Router... to place a synthetic device on the topology.
Enter a display name (e.g. "new-core-rtr"). The node appears with a dashed cyan border to distinguish it from real devices.
The hypothetical router has no area membership at creation — it joins areas when you connect hypothetical links to it, matching real OSPF behavior where area membership is determined by interfaces, not the router.
If you connect a hypothetical router to devices in two or more areas, it is automatically classified as an ABR.
Right-click a hypothetical router to remove it (all connected hypothetical links are cascade-deleted) or to add links/simulate failures.

Hypothetical links:

Right-click a node (real or hypothetical) and select Add Hypothetical Link... to create a synthetic link between two devices.
Click the source device on the canvas, then click the target device.
Select the OSPF area for the link. If both devices share exactly one common area, it is auto-selected. If they share multiple areas, choose from a dropdown (shows area ID and protocol). If no common area exists, all areas from both devices are offered with a warning that the other device will be added to the selected area.
Set the OSPF cost (symmetric by default, or set forward/reverse independently).
Hypothetical links appear as dashed green edges on the canvas and are included in SPF computation.

SRLG (Shared Risk Link Group):

Right-click a node and select Start SRLG Group... to begin defining a group.
While the SRLG panel is open, right-click additional nodes or links and select Add to SRLG Group to accumulate members.
Name the group and click Create SRLG. The group appears as a single mutation in the Mutations tab, but all members fail simultaneously during SPF computation.
Load Saved SRLG: Click the "Load Saved SRLG" dropdown to populate members from a persistent SRLG group. Saved SRLGs are managed via Admin > Monitoring > SRLG Groups... (network-scoped, stores link memberships in the database). When a saved SRLG is applied, the server expands it to individual link failures automatically.

SRLG Groups (Admin > Monitoring):

Manage persistent SRLG definitions that can be reused across simulation sessions. Open via Admin > Monitoring > SRLG Groups.... Select a network, then create/edit/delete SRLG groups with named link members. Each SRLG is scoped to a single network and stores its member links in the database. These groups appear in the "Load Saved SRLG" dropdown during simulation.

Simulation panel:

The instance selector at the left of the tab bar chooses the protocol instance being simulated. The canvas can display several instances, but a simulation evaluates one at a time.

Switching instance keeps the checked areas and node positions. Simulation and area-cloud focus follow the selected instance. Existing changes are retained; changes that do not apply to the new instance are ignored. With only one visible instance, the selector is a label.

The simulation panel has five tabs:

Tab	Purpose
Mutations	Review, enable, disable, or remove simulated changes.
Impact	Inspect isolated devices, affected links, and estimated traffic redistribution.
Paths	Compare baseline and simulated paths: cost, route type, and hops.
Assessment	Test individual node or link failures in a batch.
Scenarios	Save, load, update, or share named sets of changes.

Simulation Mutations Tab

Open Tools > Simulation > Mutations to review the changes in the current scenario. Add failures or hypothetical elements using the action buttons and canvas context menu described above.

Use each entry's checkbox to include or exclude it, or remove it when it is no longer part of the case. Undo and Redo let you compare successive choices. An SRLG represents a set of links that fail together; check its members before using it for a shared-risk assessment.

Check the protocol instance selector before interpreting results. Changes outside that instance may be retained in the list without affecting its calculation. Use Scenarios to save the set of changes.

Simulation Impact Tab

Open Tools > Simulation > Impact after adding changes. Review isolated devices, affected links, and estimated traffic redistribution. Utilization badges use ok below 80%, warning from 80% to below 95%, and critical at 95% or above.

Compare before and after values and inspect the affected links. An estimate depends on the available traffic measurements and model; it does not guarantee spare capacity during a real change. Where BGP traffic is estimated from prefix counts, read that label before treating the value as measured traffic.

If the result seems unexpectedly empty, check the selected instance, enabled mutations, discovery coverage, and available traffic data. A missing measurement is not zero utilization.

Simulation Paths Tab

Open Tools > Simulation > Paths to compare baseline and simulated routes. Use the category filters to inspect broken, increased-cost, decreased-cost, new, or rerouted paths. Compare the hop list and cost, and note any hypothetical elements marked [SIM].

Read the path explanation when data is incomplete. OSPF and IS-IS use the changed topology model. EIGRP can use recorded installed alternatives but does not predict a new DUAL calculation. In Time Travel, those alternatives retain the coverage and sample time of the historical data.

Simulation Assessment Tab

Open the Assessment tab in the simulation panel to run a batch assessment. This iterates every link or every node in the topology, simulates individual failure for each, and shows which devices become unreachable (isolated from the network).

Only failures that cause actual device isolation are shown — redundant links/nodes whose failure has no isolation impact are filtered out. Click any row to expand it and see the names of the unreachable devices.

Results are displayed in a sortable table. Click column headers to sort by devices lost or entity name. Use Export CSV to download the full assessment for offline analysis.

Simulation Scenarios Tab

Simulation supports saving mutation sets as named scenarios for reuse, via the Scenarios tab in the simulation panel:

With mutations active, the tab shows a "Save current mutations" row: type a name and click Save new, or click Update "name" to overwrite the loaded scenario with the current mutations.
The list below shows all saved scenarios (own + shared). Click any scenario to load its mutations onto the canvas; hover for share/delete actions on your own scenarios.
Scenarios are stored per-user and scoped to the protocol instance or network.
Use scenarios to preserve pre-validated maintenance plans, compare alternative failure mitigation strategies, or share standard test cases across sessions.

Trying a Simulation

Click the gear button in the bottom bar (or Tools > Simulation).
Right-click a core link and select Simulate Failure.
Open the Impact tab to see traffic redistribution and which devices become isolated.
Open the Paths tab to compare original vs. new path costs for affected device pairs.
Right-click another link and select Change Cost... to test a traffic engineering adjustment.
Open the Assessment tab to run a batch analysis of all links and identify the most critical failure points.
Right-click a device and select Add Hypothetical Link... to test adding redundancy.
Right-click empty canvas space and select Add Hypothetical Router... to model a planned new device. Connect it with hypothetical links to evaluate the routing impact.
Use Undo in the Mutations tab to step back through changes.
Click Go Live to return to the live topology.

Tip: Simulation is useful for pre-validating maintenance plans. Before shutting down a link for maintenance, simulate the failure to verify that all devices remain reachable, that traffic redistribution stays within capacity, and that no new single points of failure are created. Use the batch assessment to identify the network's most critical links before they become a problem. For incident post-mortems, combine Simulation with Time Travel to replay a past outage and test whether proposed topology changes would have prevented the impact.

9. Alerts & Incidents

Alert System

Osprey monitors the network and fires alerts when conditions are met. Access via the Alerts menu in the menu bar.

Built-in Alert Rules

One system alert rule is seeded by default:

SNMP Target Failure: Auto-disables targets after 10 consecutive poll failures (configurable per network under Enrichment > Advanced > Auto-disable after).

Create additional alert rules under Admin > Monitoring > Alert Rules. The Alert Rule Manager provides templates for common rules (congestion warning/critical thresholds, interface error rate) that you can add with one click. You can also create custom rules from scratch.

The Alert Rule Manager: each rule with its severity, the event type it matches, its scope, notification channels and enable toggle

Creating an Alert Rule

Admins and engineers can open Admin > Monitoring > Alert Rules and create a rule from a template or from scratch.

Give it a descriptive name, such as “Core link removed”, and choose a severity.
Select the event to watch. For this example, use link_removed; link_* also matches other link changes and will be noisier. Traffic and interface-error templates provide the relevant threshold fields.
Choose the network and, if needed, a narrower scope. Check the Watching summary before saving.
Set a Cooldown, the minimum time between repeated alerts for the same entity. Custom accepts seconds. This limits repetition; it is not a delay before the first alert.
Select notification channels and, for each, whether to notify on firing, resolution, or both. Save the rule and check that it is enabled.

A channel's Test button checks delivery, not whether your rule matches an event. If an expected alert is missing, check its event type, scope, threshold, cooldown, maintenance windows, and ignored alerts.

Alert Bell

The bell icon in the top-right header shows the count of firing alerts (displays "9+" when more than 9 are active). Click the bell to open a dropdown panel showing up to 20 active alerts. Each alert in the dropdown displays:

A severity-colored indicator dot (red for critical, yellow for warning, blue for info)
Alert summary text
Router ID (if applicable) and relative timestamp (e.g., "5m ago")
An Ack button to acknowledge firing alerts directly from the dropdown

The dropdown closes when you click outside it or press Escape.

Managing Alerts

Alerts > Active Alerts: Opens the Activity Tray on the Alerts tab, filtered to currently firing alerts (severity badges, acknowledge/resolve actions). If the tray is already open, it switches to this view.

Alerts > Alert History: Opens the Activity Tray on the Alerts tab with the filter set to All, for browsing current and past alerts.

Action	Effect
Ack	Records that someone is handling the alert. It does not fix or resolve the condition.
Resolve	Closes this alert instance. A later matching event can raise another alert.
Ignore	Closes the alert and permanently suppresses this rule for this particular entity. Use it only when you also want to stop future matching alerts.
Delete	Removes the alert record; it does not suppress the rule. Requires an admin or engineer.
Clear all	Deletes all alert records, not just the rows in your current filter. Requires an admin or engineer.

All roles can acknowledge, resolve, and ignore alerts. A link's alerts can appear together across areas or address families. Group actions apply to the group's alerts; Ignore suppresses the rule-and-entity combinations represented in that group, not every possible future rule for the link.

Undo Ignore: ask an admin or engineer to open Admin > Monitoring > Alert Rules > Ignored Alerts and remove the suppression. The next matching event can then raise an alert again. Resolving an alert or deleting its record does not undo an existing suppression.

Admin > Monitoring > Notification Channels (admin or engineer): Configure where alerts are sent:

Webhook: POST JSON to any URL (custom headers supported)
Email: SMTP delivery (STARTTLS auto-negotiation, implicit TLS on port 465, optional authentication)
Slack: Incoming webhook with formatted messages (severity emoji, rule name, summary)
Microsoft Teams: Incoming webhook with MessageCard format (color-coded severity)
In-App: Delivered via the activity tray (no external configuration needed)

Each channel has a Test button that sends a real test notification to verify delivery. If delivery fails, the specific error is displayed (e.g., SMTP connection refused, HTTP 404).

Webhook Payload

Generic webhooks send a JSON object with alert_id, rule (the rule's name), severity, status, summary, and fired_at. router_id is included when the alert has one. Use alert_id to associate notifications about the same alert; fired_at remains its firing time, including in a resolution notification.

A configured message template adds a message field; it does not replace the JSON envelope. Templates use Go template syntax, for example {{.rule}}: {{.summary}}. Test delivery to your receiver before relying on a custom template.

Incident Correlation

Osprey's event correlation engine automatically groups related topology events into incidents. For example, if a core router goes down, the subsequent link failures on all its interfaces are grouped into a single incident with the device failure identified as the root cause.

Incidents appear in:

The Active Incidents card on the dashboard.
The Activity Tray (bottom-left), mixed with standalone events.
Incident cards with severity-colored borders, collapsible child events, and clickable root cause.

Correlation groups events within a 30-second window and prioritizes device failures over their dependent symptoms.

Acknowledging an incident records that someone is handling it. It does not disable automatic resolution: link and device failure incidents can still close when their affected links recover. The acknowledgment remains in the incident history.

Area Partition Incidents

OSPF does not signal an area partition (RFC 2328 §3.7): when the links joining two halves of an area fail, each half keeps flooding its own LSDB under the same Area ID, and the backbone quietly routes between the halves as if they were separate areas. Osprey detects this when two or more healthy recorders on one area persistently report device sets with zero overlap, and raises a dedicated incident (area_partition).

The incident names both islands (which recorders see which routers) and classifies what the split means for your network:

Consequence	Severity	Meaning
bridged	warning	Every island still has an ABR connected to area 0 — traffic between the halves flows via the backbone. Degraded and suboptimal, but connected.
isolated	critical	An island has no ABR with backbone membership — its prefixes are no longer summarized into area 0 and it is cut off from the rest of the AS. The summary names the isolated routers.
backbone_partition	critical	Area 0 itself is split: inter-area routing between the halves is broken. Configure virtual links (RFC 2328 §15) or repair the backbone link.
unknown	warning	No recorder monitors area 0 for this protocol instance, so isolation cannot be determined. Add an area-0 recorder for full classification.

Where you see it:

Sidebar: the area row shows a pulsing SPLIT chip (amber = degraded, red = critical); use its question-mark help for the incident summary naming the islands.
Topology canvas: a warning banner appears at the top when a visible area is partitioned, and every link gets a colored halo per island — each island is tinted by the recorder that still sees it, so the split is visible at a glance. Both islands stay on the map (each recorder's data coexists; a link's reporting recorder is also shown in its detail panel).
Activity tray: the incident appears with a "partition" badge. Expand it to see the consequence, each island's recorders and routers (click a router to highlight it on the canvas — the island dots match the canvas halo colors), and once healed, why it resolved.

What to do: Investigate the links between the reported islands. The incident clears when the recorders' device sets overlap again. Loss of monitoring does not prove recovery: a silent recorder or engine restart leaves the incident open. Disabling or deleting a required recorder resolves it as no longer observable, rather than healed.

Detection requires at least two healthy recorders, two devices in each island, five minutes of stable observations, and three confirming evaluations. An unchanged topology can still be healthy. IS-IS partition detection is unavailable. Partition badges are live-only and are hidden in Time Travel.

Maintenance Windows

Admin > Monitoring > Maintenance Windows

Schedule maintenance periods to suppress alerts:

Click Create Window.
Set the start and end time.
Choose the scope: global, specific network, routing domain, protocol instance, area, or device.
Add a description.

During an active maintenance window, matching alerts are suppressed. The window appears with status indicators: scheduled, active, or expired.

10. SSH Terminal

Osprey provides a browser-based SSH terminal to connect directly to network devices.

The terminal is available to administrators and engineers. Operators are read-only and cannot open SSH or Telnet sessions.

Connecting

Right-click a device on the canvas and select SSH to [device name].
Or click the SSH button in the Node Detail Panel.
Type your username at the Login: prompt and press Enter.
Osprey connects to the device, and the device's own banner and password prompt are relayed into the terminal — type your password there, exactly as in a native SSH client. A wrong password re-prompts against the device.

The SSH terminal opening a session to a router, waiting at the Login: prompt

The terminal uses xterm.js with full interactive support. The SSH connection is proxied through the Osprey API server via WebSocket. The SSH proxy can be completely disabled by an administrator via Admin > System Settings > Security > Transport > Disable SSH Terminal Proxy. When disabled, the SSH context menu item and SSH button are hidden across the UI, and WebSocket connections are rejected at the API level.

Telnet fallback is available but disabled by default for security (telnet transmits credentials in cleartext). To enable it, set Allow Telnet Fallback in Admin > System Settings > Security. When enabled and SSH fails, the proxy falls back to telnet (port 23) with a warning displayed to the user.

Legacy Device Compatibility

The SSH proxy prefers modern algorithms and offers legacy fallbacks for older devices. These include CBC/3DES ciphers, SHA-1 key exchange, hmac-sha1-96, and ssh-rsa host keys. RC4 and DSA are excluded. Host-key verification still applies when a legacy algorithm is used.

Host Key Verification

On the first connection to a device, Osprey records its SSH host key (Trust On First Use). On later connections it checks the device still presents the same key. If the key has changed, Osprey refuses the connection and shows a red banner in the terminal — this protects against man-in-the-middle attacks.

SSH terminal refusing a connection because the offered host-key fingerprint differs from the stored fingerprint

A changed key is not proof of an attack: the device may have been replaced or given a new SSH key. If you cannot independently verify the change, leave the connection blocked. Do not clear the stored key just to dismiss the warning.

If the change is expected — the device was re-keyed or replaced (RMA, certificate rotation) — an administrator can resolve it from the terminal. The banner shows the stored and offered key fingerprints; verify out-of-band that the offered fingerprint is the device's real new key, then click Clear stored key & reconnect and confirm. Osprey removes the stored key, reconnects, and trusts the device's current key. The action is recorded in the audit log (who cleared which key, and when). Non-administrators see the warning but must ask an administrator to clear the key.

Session Recording

If enabled by an administrator via Admin > System Settings > Security > Transport > Record terminal sessions (the ssh.session_recording system setting), the device output of SSH/telnet sessions — including the banner and login prompts — is recorded for audit purposes. Osprey does not record the input stream. Text echoed back by the device is part of its output and can appear in the recording. Administrators and engineers can review recordings under Admin > Device Sessions. Session log retention is configurable in Admin > System Settings > Retention > SSH Session Logs (default: 90 days).

When OSPREY_ENCRYPTION_KEY is configured, session recordings are encrypted at rest using AES-256-GCM before storage. Older plaintext recordings remain readable.

Session History

Admin > Device Sessions

Browse all SSH sessions with:

Device, Protocol, Osprey User, Device Account, Client IP, Started, Duration, and bytes sent/received
Terminal-style log viewer for recorded sessions (click a row, or View Log)
Filter by protocol, and search across device name, router ID, Osprey user and device account

The Device column shows the device's hostname; when none was recorded it falls back to the router ID, shown dimmed. Osprey User is the Osprey account that opened the session — it reflects the account's current name, so renaming a user also changes it on their earlier sessions. Device Account is the username supplied for the SSH or Telnet login. It records the attempted account, not proof of a successful login. Older sessions show Not recorded; their device account cannot be reconstructed.

11. Administration

Administrative and monitoring features are under the Admin menu in the menu bar. The menu is visible to users with admin or engineer roles. Engineers can access monitoring features (Alert Rules, SNMP Targets, Credential Profiles, Notification Channels, Maintenance Windows, SRLG Groups, Device Sessions) but cannot manage users, system settings, API keys, audit logs, or backups. Operator-role users cannot see the Admin menu.

Users & Security

User Management

Admin > Users & Security > Users

Create users: Set username, password, display name, and role (admin, engineer, or operator).
Edit users: Change display name, role, or active status.
Reset passwords: Admin can reset any user's password.
Delete users: Remove user accounts (cannot delete yourself).

Password complexity requirements are enforced per the settings in Admin > System Settings > Security (see System Settings below).

Admin > Users & Security > Login Sessions

View currently logged-in users:

Username, IP Address, User Agent, Last Activity
Activity status: online (active), idle, offline
Force Logout: Revoke individual sessions or all sessions for a user
Auto-refreshes every 15 seconds

API Keys

Admin > Users & Security > API Keys

Create API keys for headless or automated access:

Click Create API Key.
Set a name, role (admin/engineer/operator), and optional expiration. Leave Read-only access checked for inventory, alerts, events and the supported observation reports. Uncheck it only when the integration needs the role's broader permissions.
The raw key is shown once -- copy it immediately.
Use the key via HTTP header: X-API-Key: osprey_<key>

API keys bypass JWT authentication and are ideal for scripts, monitoring integrations, and CI/CD pipelines.

Read-only access is enforced by the server and excludes changes, terminal access, WebSockets and endpoints outside its allowed observation set. The operator role alone is not read-only: it can also change layouts and handle or ignore alerts. Use a separate key per integration and revoke it when no longer needed. When connecting to an older release, verify that it supports the read-only restriction; an older server can ignore an unknown creation field.

Read-only keys require Osprey 1.4.3 or later. To inspect refused operations, open Admin > Audit Log, select entity type API key and action Read-only key denied. Use the key's ID to identify which integration needs attention. Repeated denials are sampled, so this is not a complete request history. A refusal does not update the key's Last Used timestamp.

Single Sign-On (SSO)

Admin > Users & Security > Authentication

Osprey supports OpenID Connect sign-in through an identity provider. Users are provisioned automatically on first sign-in and their role follows your configured IdP group mapping.

Identity-provider integration acceptance testing is still pending, including Entra ID, Okta, Keycloak and Active Directory. Before rollout, validate sign-in, group-to-role mapping and, if enabled, provisioning with your provider.

Setup:

Set the External URL under Admin > System Settings > Authentication — the canonical HTTPS address of your Osprey installation (e.g. https://osprey.example.com). All redirect URIs derive from it.
Open Admin > Users & Security > Authentication and click Add OIDC provider.
Enter the Issuer URL and Client ID from your IdP's app registration; add the Client secret if your registration is a confidential client (public clients using PKCE need none). For an IdP on a private/RFC1918 address, enable Allow provider on a private network.
Copy the displayed Redirect URI into your IdP's app registration.
Configure the role mapping: each row maps an IdP group to an Osprey role; the highest matched role wins (admin > engineer > operator). The default role applies when no group matches — set it to Deny access to admit only mapped groups. Use the built-in preview to test group combinations.
Click Test to verify TLS, discovery, and JWKS reachability per check, then enable the provider. It appears as a button on the login page.

SAML 2.0: Click Add SAML provider and supply the IdP metadata URL or XML. Copy the displayed SP metadata URL into the IdP to register Osprey. Then map the assertion's group attribute to Osprey roles.

Osprey creates its signing keypair automatically. Users start sign-in from the provider button on Osprey's login page. IdP-initiated sign-in is unsupported.

LDAP / Active Directory: Click Add LDAP provider. Directory users sign in through the normal username/password form. Osprey verifies their password with the directory and applies the configured group mapping.

Configure:

A directory URL. Use ldaps://, or ldap:// with StartTLS; unencrypted LDAP fails the connection test.
An optional search account (Bind DN and password), and the Base DN.
Resolve nested groups for Active Directory when transitive membership is needed.
A Group search filter for directories without memberOf, such as (&(objectClass=groupOfNames)(member=%s)).

Local accounts are authenticated locally and are not retried against LDAP. Directory outages are logged and do not count as failed-password attempts toward Osprey's lockout.

Notes:

Roles of SSO users are re-evaluated at every sign-in — the IdP is the source of truth. Manually changing an SSO user's role in User Management is disabled for that reason; adjust the group mapping instead.
Entra ID omits the groups claim beyond 200 groups ("groups overage"). Prefer app roles, or enable Fetch groups via userinfo on the provider.
Local-login policy (Admin > System Settings > Authentication): enabled (default), admins_only (password form collapses behind a link), or disabled (form hidden; administrators can still reach it via /?local=1). Administrators can always sign in with a password — a dead IdP never locks everyone out.
Linking an SSO identity to an existing local account by email is off by default (email reuse at an IdP is an account-takeover vector). When off, such sign-ins fail with "an account with this email already exists".
Disabling or deleting a provider revokes all sessions of its users immediately; remaining access ends within the access-token lifetime (15 minutes by default).
Every sign-in event (success, failure with reason, SSO, token replay) is recorded in Admin > Audit Log under entity type auth.

Automatic provisioning (SCIM 2.0): An identity provider can create, update, and deactivate Osprey accounts.

Open Admin > Users & Security > Authentication.
Generate a SCIM provisioning token and copy it; it is shown once.
Configure the IdP with https://<your-osprey>/api/v1/scim/v2 and the token as its bearer credential.

Provisioned users start with the read-only operator role and sign in through SSO. Their role is updated from the group mapping at sign-in. Deprovisioning deactivates the account and ends its sessions within minutes. Revoke a compromised token from the same screen; revocation preserves its history.

Break-glass recovery (all IdPs down, or all admins locked out) — on the Osprey host:

# Reset a password (also converts an SSO account back to local login):
osprey auth reset-password admin --db-url "postgres://osprey:<pw>@localhost:5432/osprey?sslmode=disable"
# Re-enable password login for all roles:
osprey auth enable-local-login --db-url "..."
# Disable a compromised provider and revoke its users' sessions:
osprey auth disable-provider <name> --db-url "..."
# Remove a lost second factor for one account:
osprey auth reset-mfa admin --db-url "..."
# Emergency only: remove mandatory MFA enrollment for all roles:
osprey auth clear-mfa-requirement --db-url "..."

Use the real database connection string in place of .... Prefer resetting the affected account's MFA over relaxing the policy for everyone. After recovery, enroll a new factor and restore any MFA requirement you removed under Admin > System Settings > Authentication.

Device Sessions

Admin > Device Sessions

See SSH Terminal > Session History above.

Monitoring

Alert Rules

Admin > Monitoring > Alert Rules

Create, edit, enable/disable, and delete alert rules. System rules (e.g., SNMP Target Failure) can only be toggled, not edited or deleted. Templates for common traffic and error rules are available via the Add from Template button. See Alerts & Incidents for details on alert behavior.

SNMP Targets

Admin > Monitoring > SNMP Targets

Manage devices polled for traffic statistics:

Add targets with IP, SNMP version, and credentials
Auto-discover: Discover devices from seed IPs
Monitor status: active, disabled, consecutive failures
Targets auto-disable after a configurable number of consecutive failures (default 10, configurable per network under Enrichment > Advanced > Auto-disable after)
Re-enable manually to resume polling

Credential Profiles

Admin > Monitoring > Credential Profiles

Create reusable SNMP credential templates:

v2c profiles: Named community string
v3 profiles: Username, authentication (MD5/SHA), privacy (DES/AES)

Profiles can be referenced by multiple SNMP targets and recorders, eliminating credential duplication.

Security: All SNMP credentials (community strings, v3 auth/priv passwords) are encrypted at rest in the database using AES-256-GCM when OSPREY_ENCRYPTION_KEY is configured. The Debian installer generates this key automatically. API responses always mask credentials with ***.

Notification Channels

Admin > Monitoring > Notification Channels

See Alerts & Incidents > Managing Alerts for channel type details (webhook, email, Slack, Teams, in-app).

Maintenance Window Administration

Admin > Monitoring > Maintenance Windows

See Alerts & Incidents > Maintenance Windows for setup details.

System Settings

Admin > System Settings

Runtime configuration in a tabbed layout with a vertical sidebar for section navigation (Display, Topology, Routing, Retention, Security, Authentication, License). Each tab shows a blue dot when it has unsaved changes. Settings are saved all at once with the Save button. The dialog warns you before discarding unsaved changes. A Reset to Defaults button at the bottom-left restores all factory defaults.

System Settings on the Display tab, with the section list on the left and Reset to Defaults, Cancel and Save along the bottom

Display Section

Device Name Format: How devices are labeled across the UI (events, alerts, incidents, diagnostics). Individual users can override this for the topology canvas via View > Node Labels. IS-IS devices display hostname from TLV 137 (Dynamic Hostname) as the primary label; the name fallback chain is: hostname > router_id > system_id.
- hostname -- SNMP sysName or IS-IS Dynamic Hostname (TLV 137) (default)
- dns -- Reverse DNS (PTR) name
- router_id -- OSPF router ID or IS-IS system ID
- hostname_ip -- Hostname with router ID in parentheses
OSPF Area ID Format: How OSPF area IDs are displayed throughout the application — sidebar, canvas, reports, alerts, and panels. This is purely visual; stored values always remain in dotted quad format. This setting does not affect IS-IS levels, which are always displayed as "Level 1" / "Level 2".
- dotted_quad -- Standard dotted quad notation, e.g. 0.0.0.0, 0.0.0.1, 0.0.1.0 (default)
- decimal -- Decimal integer, e.g. 0, 1, 256. Shorter and often matches what is configured on routers (router ospf 1 / area 0)
IGP Area Coloring: When a device runs both OSPF and IS-IS simultaneously, this determines which protocol's area membership is used for area-based coloring on the canvas.
- OSPF areas -- Color by OSPF area membership (default)
- IS-IS areas -- Color by IS-IS level membership
Area Cloud Auto-threshold: Number of areas that triggers automatic activation of Area Cloud Overview mode (range 2--100, default: 10). When the user checks this many or more areas in the sidebar, the canvas switches to the aggregated cloud view. Users can manually toggle the view regardless of this threshold. Set to a high value (e.g., 100) to effectively disable auto-activation.

Topology Section

Stale Device Retention (hours): How long unreachable devices/links remain visible before auto-deletion. Range: 1--8760. Default: 168 hours (7 days). A warning appears if set below 24 hours, as brief maintenance windows could trigger device removal.

Routing Section

Administrative distance (AD) determines which protocol's routes are preferred when multiple protocols advertise the same prefix. Lower values are preferred. These settings affect the Route Path computation and the per-router RIB view.

These values apply across the entire Osprey installation. Defaults follow Cisco conventions and are not learned from the routers. Other vendor defaults or locally changed distances can produce different route choices, especially during a protocol migration. Per-device distance overrides are not available.

OSPFv2: Administrative distance for OSPFv2 routes (range 1--255, default: 110). Applies to all OSPFv2 route types (intra-area, inter-area, external). Internal preference within OSPF (intra > inter > external) is handled by OSPF metric comparison, not AD.
OSPFv3: Administrative distance for OSPFv3 (IPv6) routes (range 1--255, default: 110). Separate from OSPFv2 to allow independent tuning in dual-stack environments.
IS-IS: Administrative distance for IS-IS routes (range 1--255, default: 115). Applies to both Level-1 and Level-2 routes.
EIGRP (internal): Administrative distance for internal EIGRP routes (range 1--255, default: 90).
EIGRP (external): Administrative distance for redistributed EIGRP routes (range 1--255, default: 170).
eBGP: Administrative distance for external BGP routes (range 1--255, default: 20). eBGP routes are learned from BMP peers in different autonomous systems.
iBGP: Administrative distance for internal BGP routes (range 1--255, default: 200). A warning appears if iBGP AD is set lower than OSPFv2 AD, as this is unusual and would cause iBGP routes to be preferred over OSPF internal routes.

Example: With default values, a prefix advertised by both OSPF (AD 110) and eBGP (AD 20) will use the eBGP path. To prefer OSPF, set the OSPFv2 AD below 20 (e.g., 15).

Retention Section

Event History: Days to keep topology events (range 1--365, default: 90).
Topology Snapshots: Days to keep time-travel snapshots (range 1--365, default: 30).
SSH Session Logs: Days to keep SSH/telnet session recordings (range 1--365, default: 90).
Audit Log: Days to keep admin audit entries (range 1--365, default: 90).
Alerts: Days to keep alert history (range 1--365, default: 90).
Incidents: Days to keep incident records (range 1--365, default: 90).
BGP History: Days to keep BGP best-path, peer and full-RIB history partitions (range 1--365, default: 90).
User Sessions: Days to keep user session records (range 1--365, default: 90).
Interface Stats: Days to keep utilization-history partitions for traffic graphs (range 1--365, default: 30). This is a global retention setting, separate from per-network polling intervals in Enrichment.

Security Section

Password Policy:

Minimum Password Length: Range 4--72 (bcrypt limit). Default: 8.
Require Uppercase Letter: Default: enabled.
Require Number: Default: enabled.
Require Special Character: Default: enabled.

Login Protection:

Max Login Attempts: Consecutive failed logins before lockout. Set to 0 for unlimited (no lockout). Default: 5. A warning appears if set to 1.
Lockout Duration (minutes): How long to lock an account after exceeding max login attempts (range 1--1440). Default: 15 minutes. This field is disabled and grayed out when Max Login Attempts is set to 0.

Transport:

Disable SSH Terminal Proxy: When enabled, the SSH terminal proxy feature is completely disabled. The right-click "SSH to" context menu item is hidden, the SSH button in node detail panels is removed, and WebSocket connections for SSH are rejected at the API level with 403. Default: disabled (SSH proxy is available). Use this in environments where the proxy is not permitted by security policy.
Allow Telnet Fallback: When enabled, the SSH terminal proxy falls back to cleartext telnet (port 23) if SSH (port 22) fails. Default: disabled. Warning: telnet transmits credentials in cleartext. This setting has no effect when the SSH terminal proxy is disabled.

Authentication Section

Global sign-in settings that apply across every identity provider. Per-provider OIDC/SAML/LDAP setup itself lives on the separate Admin > Users & Security > Authentication page -- see Single Sign-On (SSO) above.

Osprey URL: The canonical HTTPS address of this Osprey installation (the auth.external_url setting). Use the browser-facing address, including a reverse proxy if applicable. Every provider's redirect URI derives from it; this is required for single sign-on.
Local-login policy: enabled (default), admins_only, or disabled -- see the Notes under Single Sign-On (SSO) above for what each mode hides and how administrators always retain a way in.
Link SSO sign-ins to existing accounts by email: Off by default (email reuse at an IdP is an account-takeover vector).
MFA required roles (auth.mfa.required_roles): Which roles must enroll two-factor authentication -- see Two-Factor Authentication (TOTP) above.

License Section

Open Admin > System Settings > License to check the node allowance, current count, grace deadlines, and available replacement capacity. The panel also explains rejected discovery attempts.

Status	What it means
active	The installation is operating within its entitlement.
overage grace	The node allowance has been exceeded. Full operation continues for 30 days.
expiry grace	The paid license has expired. Full operation continues for 30 days.
restricted	Grace has ended, or none applied. Existing devices keep updating; new devices are admitted only within the available allowance.

Grace applies to installed licenses only. It exists so a licensed installation is not cut off while a purchase is being arranged.

Without an installed license, the evaluation allowance is 32 nodes and there is no grace. The allowance is applied when devices are discovered, and the status goes to restricted as soon as the count exceeds it. Everything already discovered keeps updating, and deleting a device frees its slot immediately. Osprey's own recorder nodes are excluded from the count; discovered network devices, including BGP-LS devices, count normally.

A network larger than the allowance. Discovery does not refuse the whole network. It admits devices up to the allowance and refuses the rest, so a 64-router network is monitored as 32 routers rather than none. The selection follows router ID in ascending order, which is stable: the same devices are chosen after a restart or a re-discovery, and an already-monitored device is never dropped to make room for a lower router ID. Links to devices that were not admitted are not drawn. A banner reports that the cap is reached and that new devices are not being added. Install a license to monitor the rest; previously refused devices are then re-discovered automatically.

Installing a license that still does not cover the current count starts a normal 30-day grace at that moment and re-discovers the devices that were refused.

Install a license: Paste the signed key and click Upload License. A valid key takes effect immediately. A license that covers the current node count also triggers rediscovery of previously rejected devices without resetting routing adjacencies.

Alternatively, place the key at the configured license_file path. Osprey adopts it if no database key exists, if it was issued later, or if it extends the expiry of the same issuance. An older file cannot replace a newer uploaded key.

After grace ends, a discovery batch containing new devices must fit the allowance in full. Existing devices continue updating. Deleting devices frees replacement capacity immediately. A licensed overage episode resets after 24 continuous hours within the allowance; evaluation records no episode, so returning below the allowance restores normal discovery without granting a grace period. An unlimited license does not become a zero-node allowance after expiry.

Audit Log

Admin > Audit Log

Audit trail of recorded administrative and authentication activity:

Columns: Timestamp, User, Action (create/update/delete/toggle/refresh), Entity Type, Entity ID, IP Address
Detail: Expand a row to inspect what changed
Filtering: By action and entity type; the API also supports user and time filters
Export: CSV download
Retention: Configurable in System Settings (default: 90 days)

Recorded actions include creating users, modifying alert rules, changing system settings, enabling/disabling recorders, deleting devices and DNS refresh triggers.

Read-only key denied records identify refused requests by key ID and owner, without recording the secret or request content. Repeated events are limited to one per key per minute, with a shared ten-per-minute budget (burst ten) per API process. Expanded details may include a count of suppressed events across all keys, not just the key in that row. These records are best-effort; absence of a record does not prove a key was unused.

Backup & Restore

Admin > Backup & Restore

Osprey offers two backup levels:

	Configuration Backup (JSON)	Database Backup (SQL)
What	Selected configuration	All PostgreSQL data; host files and encryption keys must be saved separately
Format	Readable JSON, portable	Raw SQL (pg_dump)
Use case	Migration to a new installation	Disaster recovery
Hierarchy	✅ Networks, ASes, RDs, PIs, Areas	✅
Collectors & SNMP targets	✅ (credentials redacted)	✅
Users & roles	✅ (no passwords)	✅ (with password hashes)
Alert rules & notifications	✅	✅
System settings	✅	✅
Maintenance windows	✅	✅
Topology (devices, links, interfaces)	❌ (re-discovered automatically)	✅
Canvas layouts	❌	✅
User settings (theme, preferences)	❌	✅
Icon packs (imported Visio stencils)	❌	✅
SNMP credential profiles	❌	✅
API keys	❌	✅
SSH known hosts	❌	✅
Event history & time-travel data	❌	✅
Audit log	❌	✅
Restore mode	Additive (skips existing)	Destructive (replaces all)

Export Configuration

Click Export Configuration to download a JSON file with hierarchy, recorders, users, alert rules, SNMP targets, and system settings. This backup is designed for quick migration — after restoring, topology is automatically re-discovered by the recorders.

Export Database

Click Export Database for a complete PostgreSQL dump. This includes all data: topology, canvas layouts, event history, icon packs, audit log, and everything in the configuration backup.

If export cannot start, the panel shows an error. Check database access and whether the installed pg_dump supports your PostgreSQL server version.

A failure after downloading has started can leave a partial file. Check the server logs if a download ends unexpectedly, and verify a backup with a restore test before relying on it.

Keep the encryption key with your recovery materials. The database dump includes encrypted credentials but does not include OSPREY_ENCRYPTION_KEY from the host. A restored installation needs that same key to read the credentials. See Migrating to a New Machine.

Restore Configuration

Click the file picker under Restore and select a previously exported .json file.
Review the entity count preview.
Click Import Configuration, then confirm.

Configuration restore is additive — existing entities with matching names are skipped, not duplicated. No data is deleted. Credentials (SNMP community strings, notification passwords) are not included in configuration backups — you will need to re-enter them after restore.

Restore Database

Click the file picker under Restore Database and select a previously exported .sql file.
Review the file name and size.
Click Restore Database, then confirm.

Warning: A successful database restore replaces the entire database. Save a backup before proceeding.

Osprey first stages and checks the uploaded SQL in api.restore_staging_dir (default /var/lib/osprey/restore). It checks available disk space for the staged file, configured reserve, and database/WAL headroom. Schema replacement, import, and schema verification then run in one transaction; a failure rolls that transaction back. Uploaded commands that could end the transaction early are rejected.

Restart the Osprey services after a successful restore.

Migrating to a New Machine

To migrate Osprey to a new installation with full history and working credentials:

Export the database on the source machine (Admin > Backup & Restore > Export Database).
Copy the encryption key from the source machine to the new machine:
- The key is OSPREY_ENCRYPTION_KEY in /etc/osprey/osprey.env.
Install Osprey on the new machine and configure it with the copied encryption key.
Restore the database on the new machine (Admin > Backup & Restore > Restore Database).
Restart all services after the restore completes.

Without the matching encryption key, the database restore will succeed but all encrypted credentials (SNMP communities, v3 passwords, notification channel secrets) will be unreadable. You would need to re-enter them manually.

If you only need to migrate configuration without history, use Export Configuration instead — it produces a portable JSON file that works on any installation (credentials are excluded and must be re-entered).

12. Keyboard Shortcuts

Open Help > Keyboard Shortcuts or press ? for a quick reference. The tables below also cover panel and cloud controls.

Shortcut	Action
`Ctrl+K` / `Cmd+K`	Search
`Escape`	Minimize focused panel (or close dialog / deselect)
`Shift+Escape`	Close focused panel

Panel Shortcuts

Shortcut	Action
`Ctrl+Shift+M`	Minimize all open panels
`Ctrl+Shift+R`	Restore all minimized panels

Topology Canvas

Shortcut	Action
`+` / `=`	Zoom in
`-`	Zoom out
`0`	Fit to screen
Mouse wheel (scroll)	Zoom in/out
Click + drag on canvas	Pan
Click node	Select device
Click edge	Select link
Right-click	Context menu

Cloud View Shortcuts

Shortcut	Action
`Tab`	Move focus to next cloud
`Shift+Tab`	Move focus to previous cloud
`Enter`	Expand/collapse focused cloud
`Space`	Open Area Detail Panel for focused cloud
`Escape`	Collapse all expanded clouds
Arrow keys	Navigate between clouds

Selection

Shortcut	Action
`Delete`	Delete selected device (admin only, stale/down devices)

Time Travel Shortcuts

Shortcut	Action
`Space`	Play/pause playback
Left arrow	Step backward
Right arrow	Step forward

13. Configuration Reference

Server Configuration (`/etc/osprey/osprey.yaml`)

This example uses the Debian package's BMP listener and connection limit. Without those overrides, the binary defaults to 127.0.0.1:11019 and 100 connections. Check the installed configuration when diagnosing reachability or capacity.

database:
  host: localhost              # PostgreSQL host
  port: 5432                   # PostgreSQL port
  name: osprey                 # Database name
  user: osprey                 # Database user
  password: ${OSPREY_DB_PASSWORD}  # From environment
  max_connections: 40          # Per-service pool size (5 services x 40 = 200 total)
  ssl_mode: disable            # disable | require | verify-ca | verify-full
  synchronous_commit: "on"    # Keep commit durability; advanced PostgreSQL tuning

event_retention_days: 90      # Fallback when retention.events_days has no valid system setting

nats:
  url: ${OSPREY_NATS_URL}     # nats://localhost:4222
  token: ${OSPREY_NATS_TOKEN}  # Optional NATS auth token

api:
  listen: "127.0.0.1:8080"    # API listen address (nginx proxies from 443)
  ssh_recording: false         # Fallback for session recording; overridden by the ssh.session_recording system setting
  max_restore_size: 0 # Optional hard ceiling in bytes; 0 uses live disk capacity
  restore_staging_dir: "/var/lib/osprey/restore" # Private disk-backed staging; custom packaged paths also need a systemd ReadWritePaths drop-in
  restore_database_dir: "/var/lib/postgresql" # Local PostgreSQL capacity-check path
  restore_min_free_bytes: 5368709120 # Preserve at least 5 GiB
  restore_min_free_percent: 10 # Or 10% of the filesystem, whichever is larger
  topology_cache: "on"         # Set to "off" to bypass the per-area topology cache
  cors_origins:                # Allowed CORS origins
    - "https://your-domain.com"

auth:
  jwt_secret: ${OSPREY_JWT_SECRET}  # Must be 32+ bytes
  access_token_ttl: "15m"          # JWT token lifetime
  refresh_token_ttl: "168h"        # Refresh token lifetime (7 days)
  bcrypt_cost: 12                  # Password hashing cost
  secure_cookies: true             # HTTPS-only cookies

# Credential at-rest encryption (AES-256-GCM).
# Generate: openssl rand -base64 32
# If empty, credentials are stored in plaintext (backwards compatible).
encryption_key: ${OSPREY_ENCRYPTION_KEY:-}

# License file (Ed25519-signed). Upload via Admin UI or place a newly issued
# key here; Osprey promotes it atomically after comparing the durable DB key.
# If missing/empty, the evaluation allowance is 32 nodes; see License.
license_file: /etc/osprey/license.key

topology:
  stale_retention_hours: 168   # 7 days; overridable via Admin > System Settings

snmp:
  discovery_interval_seconds: 21600  # Startup fallback only; overridden by per-network discovery_interval_hours (default 6h)
  stats_retention_days: 30         # Days to keep interface stats
  isis_bootstrap_enabled: true     # IS-IS per-area bootstrap; false = kill switch (restart collector-manager); opted-in parent also required

bmp:
  listen_address: "0.0.0.0:11019"    # Debian package default; accepts router connections
  # allowed_cidrs: []                # CIDR allowlist (empty = only bmp_target.router_ip allowed)
  max_connections: 50                # Debian package maximum concurrent BMP sessions
  max_connections_per_ip: 2          # Per-source-IP connection limit
  max_message_size: 65536            # Maximum BMP message size (64 KiB)
  allow_nat_fallback: false          # Match BMP sysName when source IP differs from target IP (NAT)
  metrics_listen: "127.0.0.1:9094"  # BMP Prometheus endpoint

bgp_history:
  enabled: true                      # Global BGP history recorder switch
  debounce_seconds: 30              # Coalesce rapid changes; 0 records immediately
  storm_ceiling_per_hour: 1000000   # Per-target safety ceiling
  rib_buffer_cap: 500000             # Full-history debounce buffer bound

metrics:
  enabled: true
  listen: ":9090"             # Prometheus metrics endpoint

logging:
  level: info                 # debug | info | warn | error
  format: text                # json | text

Environment Variables (`/etc/osprey/osprey.env`)

Variable	Required	Description
`OSPREY_DB_HOST`	Yes	PostgreSQL host (default: `localhost`)
`OSPREY_DB_PASSWORD`	Yes	PostgreSQL password (auto-generated on install)
`OSPREY_NATS_URL`	Yes	NATS server URL (default: `nats://127.0.0.1:4222`)
`OSPREY_NATS_TOKEN`	No	NATS authentication token (auto-generated on install if NATS is configured with token auth)
`OSPREY_JWT_SECRET`	Yes	JWT signing secret (auto-generated, 32+ bytes)
`OSPREY_ENCRYPTION_KEY`	Recommended	AES-256 key for SNMP credential at-rest encryption (auto-generated, base64-encoded 32 bytes). If unset, credentials are stored in plaintext.
`OSPREY_METRICS_LISTEN`	No	Override metrics listen address per service. Set in each service's systemd unit: engine `:9090`, collector-manager `:9091`, SNMP poller `:9092`, API `:9093`, BMP server `:9094`.

The environment file is created at install time with PLACEHOLDER values that the postinst script replaces with randomly generated secrets. The file is owned by root:osprey with mode 0640 to protect credentials.

Service Ports

Service	Port	Purpose
API	8080	REST API + WebSocket
nginx	443 (HTTPS), 80 (redirects to 443)	HTTPS frontend + API proxy
BMP Server	11019 (TCP)	BGP Monitoring Protocol listener
Engine metrics	9090	Prometheus
Collector Manager metrics	9091	Prometheus
SNMP Poller metrics	9092	Prometheus
API metrics	9093	Prometheus
BMP Server metrics	9094	Prometheus
NATS	4222	Message bus
PostgreSQL	5432	Database

Systemd Services

Osprey runs as five systemd services grouped under osprey.target:

Service	Unit Name	Runs As	Description
Engine	`osprey-engine`	`osprey`	Topology processing, event correlation, snapshot creation
API	`osprey-api`	`osprey`	REST API, WebSocket, SSH proxy
Collector Manager	`osprey-collector-manager`	`root`	GRE tunnel and SNMP discovery recorders (requires NET_ADMIN + NET_RAW)
SNMP Poller	`osprey-snmp-poller`	`osprey`	Interface statistics and device enrichment
BMP Server	`osprey-bmp-server`	`osprey`	BGP Monitoring Protocol listener (TCP 11019)

All five services depend on PostgreSQL and NATS (After=postgresql.service nats-server.service). They automatically restart on failure (Restart=on-failure, RestartSec=5) and have a file descriptor limit of 65536 (LimitNOFILE=65536).

# Check the target and each Osprey service
systemctl status osprey.target 'osprey-*.service'

# Restart all services
sudo systemctl restart osprey.target

# Restart a single service
sudo systemctl restart osprey-api

# View logs for a specific service (follow mode)
sudo journalctl -u osprey-api -f
sudo journalctl -u osprey-engine -f
sudo journalctl -u osprey-collector-manager -f
sudo journalctl -u osprey-snmp-poller -f
sudo journalctl -u osprey-bmp-server -f

# View recent logs (last 100 lines, no pager)
sudo journalctl -u osprey-engine --no-pager -n 100

# View logs since last boot
sudo journalctl -u osprey-api -b

# Enable/disable a service
sudo systemctl enable osprey-api
sudo systemctl disable osprey-snmp-poller

File Locations (Debian Package)

Path	Contents
`/usr/bin/osprey`	Main binary (all subcommands)
`/etc/osprey/osprey.yaml`	Server configuration
`/etc/osprey/osprey.env`	Environment secrets (0640 root:osprey)
`/etc/osprey/nats.conf`	NATS server configuration
`/etc/osprey/certs/`	TLS certificate and key
`/usr/share/osprey/web/`	Frontend static files (served by nginx)
`/etc/nginx/sites-available/osprey`	nginx site configuration
`/var/lib/osprey/`	Data directory (owned by osprey user)
`/var/lib/nats/jetstream/`	NATS JetStream data

nginx Configuration

The default nginx site (/etc/nginx/sites-available/osprey) provides:

HTTP to HTTPS redirect (port 80 to 443)
TLS termination with self-signed certificate
API reverse proxy: /api/ requests forwarded to 127.0.0.1:8080
WebSocket support: Upgrade and Connection headers proxied, with 86400s read timeout
SPA fallback: all non-API, non-asset requests serve index.html
Cache headers: hashed assets (/assets/) cached for 1 year with immutable; index.html is never cached
Security headers: X-Content-Type-Options, X-Frame-Options, Strict-Transport-Security

14. Troubleshooting

Start with the panel's selection, mode, and data status. Then check the relevant source. Service logs are useful once you know which part of collection or display is failing.

Symptom	Start here
An expected alert is missing	Check the rule's event, scope, threshold and cooldown, then maintenance windows and Ignored Alerts.
An alert exists but no notification arrived	Test its notification channel, then check that the rule uses that channel for the relevant firing or resolution action.
SSH will not connect	Check reachability, credentials, and the terminal's error. For a changed host key, follow host-key verification; do not clear the key just to bypass the refusal.
No L2 neighbors appear	Check the network's L2 configuration, credentials, polling status, and whether the devices expose LLDP/CDP observations.
An MPLS or EVPN report is absent	Follow Report Missing or Disabled and the linked discovery requirements.
Backup or restore fails	Preserve the error and check Backup & Restore, especially available disk space and encryption-key requirements, before retrying.

Report Missing or Disabled

Check the areas selected in the sidebar and the report's own network or protocol selector.
Read the disabled entry's explanation. Some reports require a particular protocol; the LSDB Browser also needs access to original protocol data that BGP-LS does not provide.
For MPLS and EVPN reports, confirm that the corresponding services have been discovered. These entries appear when matching data is available.
Check whether the action requires an engineer or administrator account. A role restriction differs from missing source data.

See Reports for each report's requirements and MPLS Discovery or EVPN setup for service discovery.

Recorder Running but Topology Incomplete

Open the area's recorder cards and inspect the last received data, area verification, and any incomplete or unreachable reason.
Confirm the source covers the intended protocol instance and area or level. A source homed elsewhere can cover the area without being managed there.
Compare a known router and its neighbors with the map. Check that their areas are selected and that node filters are not hiding them.
Check the discovery method's limits: SNMP depends on the router's MIBs and reachable devices; BGP-LS depends on the export and its completion status.

Keep the distinction between collection failure and a network fault. Use Collector Status to identify the source to investigate and No Topology Data for connection and service checks.

Path Incomplete or Unavailable

Check source and destination, address family, routing domain, selected areas, and live/historical mode.
Read the path explanation's stopping reason. Missing next-hop information or area coverage can prevent a complete answer even when traffic is working.
Inspect the affected router's routing information. For paths crossing AS boundaries, also check the relevant BGP peers and routes.
In Time Travel, confirm historical coverage for the routers involved. A current route does not fill a gap in past observations.

Follow Failed Path Diagnostics for protocol-specific checks. A calculated path is not a packet test; use its stated interpretation when assessing reachability.

History Missing or Incomplete

Check the selected time and the panel's available history window. Data from before recording began cannot be recovered by enabling recording now.
Identify the missing history: topology, interface utilization, BGP routes, or EIGRP forwarding samples. They are collected separately.
For BGP Replay, check the BMP target's history mode and prefix filter. Candidate paths requires full history; a best-path history cannot reconstruct unrecorded alternatives.
For EIGRP, read the sample time and per-router coverage. A missing sample differs from an observed empty routing table.
Check retention settings. Utilization history is configured in the network's Enrichment panel. Longer retention preserves future data for longer; it does not restore records already removed.

Some information has no historical view. For example, MPLS overlays are hidden during Time Travel, utilization coloring switches off, and available LSA header metadata remains live. See Time Travel for the detailed limits.

Cannot Log In

First installation: Use admin / admin only before the required password change. Afterwards, use your chosen password.
Account locked: If login protection is enabled (Max Login Attempts > 0 in System Settings), wait for the lockout duration (default 15 minutes) or ask another admin to unlock the account. With the default settings, lockout triggers after 5 consecutive failures.
Browser cookies: Ensure cookies are enabled. Osprey uses HTTP-only secure cookies for JWT auth. Third-party cookie blocking or privacy extensions can interfere.
HTTPS certificate: Accept the self-signed certificate in your browser. Some browsers (especially Safari) block cookies on untrusted HTTPS origins.
Mixed content: If you access Osprey over HTTP instead of HTTPS and secure_cookies: true is set in the config, the browser will reject the cookies. Either use HTTPS or set secure_cookies: false (not recommended for production).
Clock skew: JWT tokens have a 15-minute lifetime by default. If the server clock is significantly ahead of the client, tokens may appear expired immediately. Ensure NTP is running on the server.

Single sign-on problems:

"Single sign-on failed / could not be verified": usually clock skew between Osprey and the IdP (id_token validation) — verify NTP on both — or a stale login attempt (the sign-in state expires after 10 minutes; just retry).
"Your account is not permitted to sign in (no matching role)": none of the user's IdP groups matches the provider's role mapping and the default role is Deny access. Fix the mapping (or the IdP group membership), not the user.
"An account with this email already exists": a local account uses this email as its username and email-linking is off (default). An admin can enable Link SSO sign-ins to existing accounts by email in System Settings > Authentication — after reading the warning — or rename/remove the local account.
The provider button is missing on the login page: the provider is disabled, or External URL is not set (check the provider's Test results and System Settings > Authentication).
Redirect lands on an IdP error page: the Redirect URI registered at the IdP does not match the one shown in the provider form (it changes when External URL changes).
Password form is gone: the local-login policy is admins_only (click "Sign in with username") or disabled (administrators: browse to /?local=1). Recovery without any working admin: osprey auth enable-local-login on the Osprey host.

No Topology Data

Check sources: Expand the area's GRE, SNMP, or BGP-LS badge. Check both process status and data freshness. A running process alone does not prove current topology coverage.
GRE tunnels: Ensure the remote router has a matching GRE tunnel configured and the IGP is enabled on the tunnel interface. For OSPF, check show ip ospf neighbor. For IS-IS, check show clns neighbor or show isis adjacency. Verify IP connectivity between the Osprey server and the router's GRE endpoint (ping).
SNMP discovery: Verify SNMP is reachable from the Osprey server: snmpwalk -v2c -c community target-ip 1.3.6.1.2.1.1.1. Check firewall rules for UDP 161. For SNMPv3, verify that engine ID, username, auth, and privacy settings match exactly.
Collector manager logs: sudo journalctl -u osprey-collector-manager -f -- look for "starting collector" or error messages.
Engine logs: sudo journalctl -u osprey-engine -f -- look for snapshot processing messages ("processing snapshot for area...").
NATS connectivity: Verify NATS is running: sudo systemctl status nats-server. Check that both the engine and collector-manager can connect (look for "connected to NATS" in their logs).
Hierarchy mismatch: If you deleted and re-created hierarchy entities (networks, areas), inspect the recorder/status rows beneath the affected area in the hierarchy sidebar. Expand the area to find a recorder that still references the old scope, then edit, disable or delete it there.

No Traffic Data

SNMP targets: Check Admin > Monitoring > SNMP Targets for target status. Active targets show a green status.
Consecutive failures: Targets auto-disable after 10 consecutive failures (configurable per network under Enrichment > Advanced > Auto-disable after). Re-enable them manually by clicking the enable toggle.
Credentials: Verify SNMP credentials are correct. For v3, auth protocol, auth password, privacy protocol, and privacy password must all match the device configuration exactly.
Firewall: Ensure UDP 161 is open from the Osprey server to the managed devices. Also verify that SNMP ACLs on the device permit the Osprey server IP.
Poller logs: sudo journalctl -u osprey-snmp-poller -f -- look for poll success/failure messages and error details.
Utilization not showing on canvas: Verify that View > Color > By Utilization is selected. Utilization data takes one poll interval (default 5 minutes) to appear after targets are added.

No BGP Data

BMP target status: Check the sidebar under the BGP protocol instance -- each target shows a status indicator (green = connected, grey = pending, red = error). Alternatively, check via GET /api/v1/bgp/targets. If pending, the router hasn't connected yet.
Router BMP config: Verify the router is configured to send BMP to the correct IP and port (default TCP 11019). Check show bmp server or equivalent on the router.
Firewall: Ensure TCP 11019 is open inbound to the Osprey server from the router's management IP.
Connection filtering: The BMP server only accepts connections from IPs matching registered BMP targets (bmp_target.router_ip). The optional bmp.allowed_cidrs in osprey.yaml adds an additional CIDR allowlist filter on top of this. If bmp.allow_nat_fallback is enabled, connections from unknown IPs are accepted and correlated by BMP sysName instead.
RIB mode: If the BMP target's RIB mode is set to none, peers are tracked but no routes are processed. Change to loc_rib or adj_rib_in_post to see route data.
BMP server logs: sudo journalctl -u osprey-bmp-server -f -- look for "BMP Peer Up", Route Monitoring activity, End-of-RIB where the selected source/RIB mode defines it, or error messages.
Engine logs: sudo journalctl -u osprey-engine -f -- look for persisted BGP best-path deltas and, for BGP-LS, observed or quiet-inferred initial-dump completion.
Peers show but no routes: Initial dump time depends on the exporter and table size. Confirm that Route Monitoring messages are arriving and that the target's RIB mode is not none. Do not wait indefinitely for End-of-RIB: some exporters omit it, and Loc-RIB has no completion marker. BGP-LS can infer completion from a quiet window unless Require observed End-of-RIB is enabled. With adj_rib_in_post, routes appear only after the router sends Route Monitoring messages.

Stale Devices Won't Disappear

Unreachable devices remain visible for the configured retention period (default 7 days). To change this:

Admin > System Settings > Topology > Stale Device Retention: Reduce the hours (minimum 1 hour). Note that setting this below 24 hours risks removing devices during brief maintenance windows.
Manual deletion: Right-click a stale or down device on the canvas and select Delete device (admin only). This permanently removes the device from the database.

Stale Devices Reappearing After Deletion

A live source can rediscover a deleted device. Check the area's recorder cards and the network's discovery settings before deleting it again. For EIGRP, deleting a device also removes its seed address, but LLDP/CDP can still find it.

Deleting an area or higher hierarchy item removes its own recorder configuration. If an enabled recorder based elsewhere also feeds that scope, Osprey blocks deletion and identifies the dependency. Manage that recorder from its home area first.

Engine / Collector Manager / SNMP Poller Shows "Down"

The System Health popover shows heartbeat-based liveness for backend services. If a service shows "Down" or "Not responding":

Verify the service is running: sudo systemctl status osprey-engine (or osprey-collector-manager, osprey-snmp-poller).
Check the service logs for errors: sudo journalctl -u osprey-engine -n 50.
Verify NATS is running -- heartbeats are published via NATS, so a NATS outage will cause all three services to appear down.
After restarting a stopped service, its status recovers to "Healthy" within ~15 seconds (the heartbeat interval).
The engine is treated as critical -- if it is unhealthy, the overall system status degrades to "Degraded" in the status bar.

WebSocket Disconnections

The bottom-right status bar shows WebSocket connection state. If it shows a red indicator:

Check that nginx is properly proxying WebSocket upgrades. The default config includes proxy_set_header Upgrade $http_upgrade and proxy_set_header Connection "upgrade" with an 86400s read timeout.
Verify the API service is running: sudo systemctl status osprey-api.
If behind an external load balancer or reverse proxy, ensure it supports WebSocket upgrades and has a sufficiently long idle timeout (Osprey WebSocket connections are long-lived).
Check for firewalls or corporate proxies that may be terminating long-lived connections.
The UI automatically reconnects when the WebSocket drops. If you see frequent reconnections, check network stability between the browser and server.

UI Crash Recovery

If a rendering error occurs in the topology canvas, activity tray, or panel stack, Osprey isolates the failure to the affected zone. A fallback panel appears with the error message and a Retry button. The rest of the UI continues functioning normally. Clicking Retry re-renders the failed zone. Switching areas or navigating away also resets the error state automatically.

DNS Names Not Resolving

PTR records: Osprey resolves reverse DNS (PTR) records for router IDs and interface IPs. Ensure PTR records exist in your DNS infrastructure for the relevant IP addresses.
Trigger refresh: Use Tools > Refresh DNS to force re-resolution of all cached IPs. The engine clears its DNS cache and re-resolves asynchronously -- results appear within seconds.
Display mode: Choose DNS Hostname under View > Node Labels, or set the system default to dns under Admin > System Settings > Display > Device Name Format. hostname uses the discovered hostname, not the PTR record.
DNS server configuration: The Osprey engine uses the system resolver (/etc/resolv.conf). Verify the DNS servers configured there can resolve PTR records for your network IP ranges.

Database Issues

# Check PostgreSQL is running
sudo systemctl status postgresql

# Check database exists
sudo -u postgres psql -l | grep osprey

# Check the database locally as the PostgreSQL administrator
sudo -u postgres psql -d osprey -c "SELECT 1;"

# Run migrations manually (use the password from /etc/osprey/osprey.env)
/usr/bin/osprey migrate --db-url "postgres://osprey:PASSWORD@localhost:5432/osprey?sslmode=disable"

# Check migration state
sudo -u postgres psql osprey -c "SELECT version, dirty FROM schema_migrations;"

Dirty migration state means a migration did not finish successfully. Do not clear the flag and retry without checking what ran: the recorded version and actual schema may differ.

Back up the database and read the service or installer error.
Check SELECT version, dirty FROM schema_migrations; as the PostgreSQL administrator.
Have the database administrator or Osprey support verify the schema against that migration and determine the correct recovery version.
Resume migrations only after the schema and recorded version agree.

Disk space: PostgreSQL requires free disk space for WAL (write-ahead log) and temporary files. If the disk is full, PostgreSQL may stop accepting writes. Free space and restart: sudo systemctl restart postgresql.

Service Won't Start

# Check service logs for the specific error
sudo journalctl -u osprey-engine --no-pager -n 50
sudo journalctl -u osprey-api --no-pager -n 50
sudo journalctl -u osprey-collector-manager --no-pager -n 50
sudo journalctl -u osprey-snmp-poller --no-pager -n 50
sudo journalctl -u osprey-bmp-server --no-pager -n 50

Common error messages and solutions:

Error	Cause	Solution
`connection refused` (port 5432)	PostgreSQL not running	`sudo systemctl start postgresql`
`connection refused` (port 4222)	NATS not running	`sudo systemctl start nats-server`
`permission denied`	File permissions wrong	Check ownership: `ls -la /etc/osprey/`. The `.env` file should be `root:osprey 0640`.
`address already in use`	Another process on the port	Find it: `sudo ss -tlnp \| grep :8080` and stop the conflicting process.
`migration dirty`	A migration failed mid-way	See Database Issues above for dirty migration fix.
`YAML parse error`	Syntax error in config	Validate: `python3 -c "import yaml; yaml.safe_load(open('/etc/osprey/osprey.yaml'))"`
`invalid JWT secret`	Secret too short	Generate a new one: `openssl rand -base64 32` and update `/etc/osprey/osprey.env`.
`encryption_key not set` warning	No encryption key configured	Generate: `openssl rand -base64 32` and set `OSPREY_ENCRYPTION_KEY` in `/etc/osprey/osprey.env`. Restart services — existing plaintext credentials are encrypted automatically on startup.

NATS Issues

# Check NATS status
sudo systemctl status nats-server

# View NATS logs
sudo journalctl -u nats-server -f

# Verify NATS is listening
ss -tlnp | grep 4222

# Test NATS connectivity (if nats CLI is installed)
nats server ping

If NATS fails to start, check that the configuration file exists at /etc/osprey/nats.conf and that the JetStream data directory /var/lib/nats/jetstream exists and is writable.

nginx Issues

# Test nginx configuration
sudo nginx -t

# Check nginx status
sudo systemctl status nginx

# View nginx error log
sudo tail -50 /var/log/nginx/error.log

# Verify the Osprey site is enabled
ls -la /etc/nginx/sites-enabled/osprey

Common issues:

502 Bad Gateway: The API service is not running or not listening on port 8080. Check: sudo systemctl status osprey-api.
SSL certificate errors: Regenerate the self-signed certificate: sudo openssl req -x509 -nodes -days 3650 -newkey rsa:2048 -keyout /etc/osprey/certs/osprey.key -out /etc/osprey/certs/osprey.crt -subj "/CN=osprey" then sudo systemctl reload nginx.
Port 80/443 conflict: Another web server (Apache, etc.) may be using the ports. Check: sudo ss -tlnp | grep -E ':80|:443'.

Performance

Large topologies: Start with Area Cloud Overview or select fewer areas. Hide unnecessary labels and area boundaries. Use Geometric for grid placement if that makes the view easier to read; arranging many nodes can still be expensive.
SNMP polling: For a non-critical network, open its Enrichment panel from the sidebar and increase Advanced > Counter poll interval. The default 5-minute interval works well for most deployments. Consider increasing the per-network PDU timeout for high-latency WAN devices.
Event and snapshot retention: Reduce retention in System Settings if disk space is constrained. Events default to 90 days; snapshots default to 30 days.
Browser memory: Close or minimize the Link Detail Panel when not actively monitoring traffic (it triggers 10-second boosted polling). Hide unnecessary columns in report panels. Minimized panels retain their state and pause active polling. For very large topologies, use filters (View > Filters) to reduce the number of rendered nodes.
Database growth: The largest tables are typically topology_event and topology_snapshot. Monitor database size with: sudo -u postgres psql osprey -c "SELECT pg_size_pretty(pg_database_size('osprey'));". The retention settings in System Settings control automatic purging.
SNMP poller concurrency: One poller service handles targets concurrently and spreads their polling times. If polling cannot keep up, increase per-network intervals and tune PDU timeouts/retries. Do not start multiple poller instances: each instance would poll the same targets and duplicate collection.

Inspect advertised SR policies

The BGP-LS → SRv6 SIDs tab lists explicit node SID advertisements, with the advertising node, topology, algorithm and behavior. Each row identifies whether it arrived via BMP or a direct BGP-LS peer. Stale means a monitoring gap; withheld attributes do not establish a usable behavior. Node, link and prefix rows show advertised capabilities/MSDs, End.X and locators. For projected IS-IS sources, the same evidence appears in the device’s SRv6 tab; an explicit SID can remain visible when its locator was not exported.

Open BGP-LS → SR policies to inspect candidate paths exported by routers. The router must export SR-policy state into BGP-LS; ordinary topology export alone may not include it. Osprey receives it through an enabled BGP-LS BMP target or an existing receive-only BGP-LS peer.

Each card shows the headend, endpoint, color, advertised preference and ordered encoded SID lists. Exporter and reporting peer are separate: a router may relay another router's policy. Different sources can disagree and remain separate. Use Refresh to read updates and withdrawals, and Include stale to inspect observations retained after a monitoring gap. Stale does not mean withdrawn.

Advertised policy state does not verify hardware installation, traffic delivery or fast repair activation. Encoding details flag the measured older Junos format; encoded SID values and raw flags must not be read as proof of installation.

Choose View in topology on a policy to open its node associations. Osprey marks the headend and numbers matched nodes in segment-list order. Click a matched node name to open its details. Choose a segment list when several were advertised; Show associated nodes toggles the highlights.

Matches use exact advertisements within the exporter’s configured routing domain. Unknown or ambiguous SID owners are not selected automatically. Stale source evidence is labeled separately. The open panel refreshes every 15 seconds; closing, minimizing or entering historical mode removes the highlights. These node associations do not show the actual traffic path or installed state.