Skip to content
NorthplaneNorthplane

Hosts and services

Northplane monitors objects: a host (something with an address) and services that belong to a host. Both share one spec (check command, interval, thresholds, notifications…) and one state model. This page shows how to create and work with them; the field-by-field reference of the spec lives in Object model, the state semantics in Checks and states.

What an object is

Section titled “What an object is”
Property Host Service
name unique per tenant; cannot be renamed (recreate instead) unique per host
host — the owning host (name or id on create; fixed afterwards)
folder path such as /prod/web, default / same; used for filtering and role scopes
labels free key/value pairs, the primary grouping mechanism (selectors, downtimes, silences, dashboards, BPI) same
spec address, checkCommand, args, templates, parents, intervals, notifications, vars, runbook … same fields; the check target is the host’s address
Delete cascades to all services of the host only the service

IDs are UUIDv7 and appear in URLs (/objects/<id>) and in the CLI (np describe <id>). Every write bumps version; updates over the API need If-Match: "<version>".

The spec fields you will touch most often (defaults apply after template resolution):

Field Default Meaning
address — host address (IP or DNS name); services use the host’s
checkCommand passive builtin:<name>, exec:<plugin>, agent:exec:<plugin>, a named CheckCommand, or passive
args — flags for builtin checks / $ARGn$ values for plugins
templates — inheritance chain, later wins (see Templates)
interval / retryInterval 60s / 15s check cadence / soft-state recheck
maxCheckAttempts 3 soft → hard
timeout 30s per-check execution limit
parents — host reachability graph
contacts, contactGroups, notifyOn — direct notifications on hard changes
stalenessAfter, stalenessText — freshness for passive/agent objects

Durations are Go durations (30s, 5m, 24h); a bare integer in JSON means seconds.

Creating hosts and services

Section titled “Creating hosts and services”

Open Objects (Objekte) and click New host (Host anlegen) or New service (Service anlegen). The dialog has four tabs; the same dialog opens for Edit on any row or detail page.

Tab Fields
Basics (Basis) Name (required; locked when editing), Folder, Host (services only; locked when editing), Address, Labels
Check (Prüfung) Check command: kind selector builtin / Command (defined) / exec / agent:exec / passive plus the name (with suggestions from the builtin list and your named commands); Arguments (one per entry); Templates (ordered, later wins); Interval, Retry interval, Max attempts, Timeout, Check period
Notifications (Benachrichtigungen) Contact groups, Contacts, Notify on (hosts: down/unreachable/recovery; services: warning/critical/unknown/recovery), Notification period
Advanced (Erweitert) Parents (hosts), tri-state Checks / Notifications / Flap detection (inherit/on/off), Threshold mode, Staleness deadline + text (services), Zone, Vars, Runbook (Markdown)

Save creates the object (POST /api/v1/hosts or /services); edit saves with the object’s version — if someone else changed it in between you get “Conflict — please reload”. The full walk-through of every dialog field is in UI → Objects.

Batch add

Section titled “Batch add”

For many similar objects use Batch add (Massenanlage) on the Objects page: one object per line,

name address [template,template] [key=value,key=value]
web-02 10.0.0.6 [linux-base] [env=prod,role=web]
db-01  10.0.0.9 [linux-base,postgres] [env=prod,role=db]

Lines starting with # are ignored. The dialog settings apply to every row: kind (host/service), folder, check command (default builtin:icmp), mode partial or all-or-nothing, and for services the host. A live preview validates each line before you submit.

The dialog calls POST /api/v1/objects:batch (reference):

{"mode":"partial","hosts":[{"name":"web-02","folder":"/prod/web","labels":{"env":"prod"},
  "spec":{"address":"10.0.0.6","checkCommand":"builtin:icmp","templates":["linux-base"]}}],
 "services":[]}

mode defaults to all-or-nothing (the first failure rolls back everything created so far and answers 422); partial keeps what succeeded. The response is {"created":n,"failed":m,"results":[{"name","id","error"}]}.

Folders and labels

Section titled “Folders and labels”
  • Folders are plain paths (/, /prod, /prod/web). They group objects in the list, can be used as a filter (GET /api/v1/objects?folder=/prod), restrict bundle exports (bundles:export?folder=/prod) and appear in role scopes. They carry no configuration.
  • Labels drive everything selector-based: list filters, downtimes and silences, business service leaves, dashboard widgets, metric queries, webhook subscriptions and bundle prune. Alert rules see the object’s labels on every state_change event (event.labels.<key>), so labels are also your routing handle in alarming (notify=mail, team=netops).

Selector grammar (comma = AND): env=prod, role in (db,cache), tier!=edge, !legacy (key absent), site (key present). Values are unquoted and cannot contain commas or parentheses. The complete grammar is in Object model.

Templates and effective configuration

Section titled “Templates and effective configuration”

Any number of templates can be listed in spec.templates; later entries override earlier ones, the object’s own fields override all templates, vars are merged key by key. The server resolves the chain on every write (unknown template → 422) and on every schedule.

GET /api/v1/objects/{id}/effective-config returns the resolved spec and the template chain (reference); the CLI shows it with np describe <id>, the UI on the object’s Configuration tab. See Templates for authoring templates and named check commands.

The object detail page

Section titled “The object detail page”

Click any row in Objects (or a problem, alert or dashboard entry) to open /objects/<id>.

Element What you see / can do
Header breadcrumb (folder, host), name, state badge with attempt (hard 3x), label chips; for services a link chip to the host; buttons Edit, Check now (queues an immediate check, POST …/check-now, permission checks:run), Downtime, Delete
Overview tab current output and long output, last check, next check, last hard change, acknowledgement, downtime, flapping; perfdata meters (bars with warn/crit marks from the check’s perfdata); “Interval & scheduling” from the effective config; Metrics charts (last 24 h, one chart per unit, thresholds as bands); hosts list their services, services list their siblings
History tab the object’s recent events (state changes, flapping, acks, downtimes …)
Configuration tab the effective configuration as a table or raw JSON, and the template chain (a → b)

Data comes from GET /api/v1/objects/{id} (object + live state), …/effective-config, GET /api/v1/events?objectId=… and POST /api/v1/metrics/query. A deleted object shows a 404 page. Charts and series are explained in Metrics and NP-TSDB.

Section titled “Finding objects: filters and shareable links”

The Objects list keeps its filters in the URL, so any view can be bookmarked or pasted into a chat:

URL parameter UI control Meaning
selector tag-icon input “Filter (e.g. env=prod)” label selector, evaluated server-side
q search-icon input “Full text…” substring over name and check output
kind select Hosts + Services / Hosts / Services object kind
state select (All, Problems, OK, Up, Warning, Critical, Unknown, Down, Unreachable, Pending) current state, filtered client-side

State tokens are problem, ok, up, warning, critical, unknown, down, unreachable, pending; kind is host or service. Example: /objects?selector=env%3Dprod%2Crole%3Ddb&state=problem&kind=service. The list loads up to 2000 objects and renders them in a virtualised table; rows link to the detail page and offer check-now, edit and delete on hover. The same parameters work on the API: GET /api/v1/objects?selector=env=prod&q=disk&folder=/prod&withState=true&limit=200&cursor=… (reference); /api/v1/hosts and /api/v1/services are kind-specific variants, /api/v1/problems lists hard non-OK objects (includeHandled=true also shows acked/downtimed ones).

Static groups

Section titled “Static groups”

StaticGroup is a bundle-only kind (spec: {members: [host names]}) produced by the Nagios importer for hostgroup definitions. It has no REST endpoint and no UI; use labels and selectors for grouping in Northplane, and treat static groups as import leftovers to convert into labels (the importer prints label suggestions for that).

Other batch operations

Section titled “Other batch operations”
  • Bundles: np export > all.yaml dumps every host, service and resource; edit and np apply. np apply --prune deletes objects that are no longer in the bundle (optionally restricted by a selector on the API). A Host document in a bundle may be accompanied by its Service documents in the same file; apply order is handled for you.
  • Downtimes and silences by selector (np downtime --selector 'env=prod,role=db' --hours 2 -m "patching") — see Maintenance.
  • Check now per object (np check-now <id>), no bulk variant.
  • AI agent / MCP: the assistant can propose and apply bundle changes under the approval policy (AI agent chat).

Deleting objects

Section titled “Deleting objects”
  • UI: Delete on a row (two-click inline confirmation) or on the detail page. Deleting a host warns that all of its services go with it.
  • API: DELETE /api/v1/objects/{id} (reference) — cascades to services, labels and check state, deschedules the checks and forgets in-memory state. Alerts and events that reference the object stay in history.
  • Bundles: np apply --prune removes everything that is not in the bundle — dry-run first (--dry-run prints would apply delete …).

Deletion is audited (host.delete / service.delete) and emits a config event.

Where to go next

Section titled “Where to go next”