From 06b5395d24cf49d25c66a418cfc93391bc1cfca9 Mon Sep 17 00:00:00 2001 From: netdatabot <43409846+netdatabot@users.noreply.github.com> Date: Fri, 11 Sep 2026 05:03:48 +0000 Subject: [PATCH] Ingest new documentation --- .../Netdata Support Bundle.mdx | 4 +- docs/Netdata Agent/Configuration/Daemon.mdx | 2 +- .../Installation/Linux/Linux.mdx | 2 +- docs/Netdata Agent/Node Identities.mdx | 122 +++++++++++++++--- .../Configuration/SNMP Profile Format.mdx | 5 +- ingest/generated_sidebar_order.json | 4 +- ingest/generated_sidebar_order.json.sha256 | 2 +- 7 files changed, 114 insertions(+), 27 deletions(-) diff --git a/docs/Developer and Contributor Corner/Netdata Support Bundle.mdx b/docs/Developer and Contributor Corner/Netdata Support Bundle.mdx index 2ab98fdc3b..9be3e7136b 100644 --- a/docs/Developer and Contributor Corner/Netdata Support Bundle.mdx +++ b/docs/Developer and Contributor Corner/Netdata Support Bundle.mdx @@ -96,7 +96,9 @@ The archive is organized into numbered directories so a person or an automated r - `05-logs/`, recent agent logs and relevant kernel messages, bounded by `--since`. - `06-state/`, persistent state such as the daemon status file used for crash analysis, database disk usage, and cloud claim state. - `07-runtime/`, live agent state read from the local API, collected only when the agent responds. -- `08-network/`, local connectivity relevant to the agent. +- `08-network/`, local connectivity relevant to the agent, including + `netdata-sockets.txt`: visible, platform-supported sockets owned by the + Netdata process tree and their native states. - `09-permissions/`, file modes, ownership, plugin capabilities, extended attributes, security contexts, and ACLs for the agent's directories and plugins. ## Include SNMP diagnostics diff --git a/docs/Netdata Agent/Configuration/Daemon.mdx b/docs/Netdata Agent/Configuration/Daemon.mdx index 8374fc58c8..d5db7bf257 100644 --- a/docs/Netdata Agent/Configuration/Daemon.mdx +++ b/docs/Netdata Agent/Configuration/Daemon.mdx @@ -131,7 +131,7 @@ A few of these settings can be individually configured in `netdata.conf`, like t | update every | `1` | The frequency in seconds, for data collection. For more information see the [performance guide](/docs/netdata-agent/configuration/performance-optimization). These metrics stored as _Tier 0_ data. Explore the tiering mechanism in the [dbengine's reference](/docs/developer-and-contributor-corner/database-engine#tiers). | | dbengine tier **`N`** update every iterations | `60` | The down sampling value of each tier from the previous one. For each Tier, the greater by one Tier has N (equal to 60 by default) less data points of any metric it collects. This setting can take values from `2` up to `255`.
`N belongs to [1..4]` | | dbengine tier back fill | `new` | Specifies the strategy of recreating missing data on higher database Tiers.
`new`: Sees the latest point on each Tier and save new points to it only if the exact lower Tier has available points for it's observation window (`dbengine tier N update every iterations` window).
`none`: No back filling is applied.
`N belongs to [1..4]` | -| memory deduplication (ksm) | `yes` | When set to `yes`, Netdata will offer its in-memory round robin database and the dbengine page cache to kernel same page merging (KSM) for deduplication. | +| memory deduplication (ksm) | `auto` | Offers the in-memory round robin database and the dbengine page data to kernel same-page merging (KSM) for deduplication.
`auto`: offer them only when the kernel supports KSM (Netdata probes for it on first use and remembers the answer; an inconclusive probe, such as one that fails under memory pressure, is retried later).
`yes`: always offer them, even if the probe found no KSM support.
`no`: never offer them. | | cleanup obsolete charts after | `1h` | See [monitoring ephemeral containers](/docs/collecting-metrics/containers-and-cgroups#monitoring-ephemeral-containers), also sets the timeout for cleaning up obsolete dimensions | | gap when lost iterations above | `1` | | | cleanup orphan hosts after | `1h` | How long to wait until automatically removing from the DB a remote Netdata host (child) that is no longer sending data. | diff --git a/docs/Netdata Agent/Installation/Linux/Linux.mdx b/docs/Netdata Agent/Installation/Linux/Linux.mdx index 0cf17bd15f..8e8ee912ce 100644 --- a/docs/Netdata Agent/Installation/Linux/Linux.mdx +++ b/docs/Netdata Agent/Installation/Linux/Linux.mdx @@ -127,7 +127,7 @@ The user running the script needs write and execute permissions in the temporary Before running the installation script, you can verify its integrity using the following command: ```bash -[ "0643708c33f613ea078ee711b25801ae" = "$(curl -Ss https://get.netdata.cloud/kickstart.sh | md5sum | cut -d ' ' -f 1)" ] && echo "OK, VALID" || echo "FAILED, INVALID" +[ "cf029d8366aa80ecaee907c40febcde6" = "$(curl -Ss https://get.netdata.cloud/kickstart.sh | md5sum | cut -d ' ' -f 1)" ] && echo "OK, VALID" || echo "FAILED, INVALID" ``` If the script is valid, this command will return `OK, VALID`. We recommend verifying script integrity before installation, especially in production environments. diff --git a/docs/Netdata Agent/Node Identities.mdx b/docs/Netdata Agent/Node Identities.mdx index ece93e602d..c92e134861 100644 --- a/docs/Netdata Agent/Node Identities.mdx +++ b/docs/Netdata Agent/Node Identities.mdx @@ -104,11 +104,11 @@ See [VM Templates](/docs/netdata-agent/vm-templates) for how to avoid this when |---------------|-------------------------------------------------------------------------------------------| | **Directory** | `vnodes/` in your [Netdata config directory](/docs/netdata-agent/configuration) | | **Format** | YAML files (`.yaml`, `.yml`, `.conf`) | -| **Identity** | User-defined GUID in config file | +| **Identity** | Configured UUID, or a UUID derived from the SNMP address | ### Configuration -Each virtual node is defined in a YAML file: +Static virtual nodes use the existing YAML format (`mode: static` is optional): ```yaml - hostname: remote-server.example.com @@ -134,9 +134,71 @@ Each virtual node GUID must be unique across your entire infrastructure. Using t ::: +### Acquiring Virtual Node Identity Through SNMP + +With go.d, a vnode can acquire its hostname and host labels independently of any metrics job: + +```yaml +- name: router + mode: snmp + mode_snmp: + address: 192.0.2.1 + version: 2c + credentials: + community: example-community + labels: + site: example-site +``` + +- `name` is required and stays the job reference even if the device's hostname changes. +- `hostname` is an optional override. Otherwise, the vnode uses a usable SNMP `sysName`, then `name`. +- `guid` is an optional UUID override. Otherwise, the exact `address` string determines the UUID. Different spellings + for the same device produce different UUIDs; port and SNMP context do not distinguish UUIDs. Supply unique UUIDs + explicitly when multiple virtual nodes use the same address. +- `labels` override acquired host labels. Removing an override restores the last acquired value. +- `mode_snmp.port` defaults to `161`, `timeout` to `5s`, and `retries` to `1`; set `retries: 0` to disable request retries. + Automatic profile matching enriches system identity; metric profile coverage is not required. + +For SNMPv3, replace `credentials` with `credentials3` and set `version: "3"`: + +```yaml + mode_snmp: + address: 192.0.2.1 + version: "3" + credentials3: + username: example-user + security_level: authPriv + auth_protocol: sha512 + auth_password: example-auth-password + priv_protocol: aes192c + priv_password: example-priv-password +``` + +The version choices are `"1"`, `2c` (default), and `"3"`. SNMPv3 supports `noAuthNoPriv`, `authNoPriv`, and +`authPriv` (default). Authentication defaults to `sha512`; privacy defaults to `aes192c`. Passwords must contain at +least eight bytes. Inactive credentials are discarded before validation and retention by go.d: authentication and privacy fields +for `noAuthNoPriv`, privacy fields for `authNoPriv`, and the credential block for the unselected version. This applies +to both files and forms; switching back requires entering the discarded credentials again. Active credentials remain +strictly validated. Optional `credentials3.context_name` selects an SNMP context. These new field names +apply to vnode acquisition; existing collector and discovery credential names are unchanged. Use literal credentials; +secret references are not supported in vnode acquisition yet. This does not rewrite source files or scrub the Agent's +saved copy of the originally submitted DynCfg payload. + +A usable `sysObjectID`, `sysName`, or `sysDescr` lets attached jobs start. Failed profile enrichment retries while +keeping usable system identity. Acquisition retries every 10 seconds after failure and refreshes complete metadata +hourly. These intervals are internal defaults. Failed refreshes retain the last usable metadata; a successful refresh +replaces acquired labels. Acquisition continues without metrics jobs, but the node is announced only by ordinary +job output. + +Acquired metadata is held in memory. After a plugin restart, jobs wait for fresh identity acquisition. Label and hostname +override edits need no network request. Credential edits reacquire metadata while retaining the last usable identity. +Changing the mode, address, context, or UUID of an existing SNMP vnode is rejected: create a replacement vnode and move +job references to it. Static vnode updates retain their existing behavior. The scripts.d and ibm.d plugins ignore +SNMP-mode file definitions and expose only static vnode configuration. + ### Creating Virtual Nodes via the GUI (Dynamic Configuration) -In addition to the YAML file method, you can create, edit, test, and remove virtual nodes directly from the Netdata UI using [dynamic configuration (dyncfg)](/docs/netdata-agent/configuration/dynamic-configuration-manager). Both methods produce a working vnode that collectors can attach metrics to, though field requirements differ — see the table below. The Vnodes GUI path is available under the go.d plugin's dynamic configuration view. +In addition to the YAML file method, you can create, edit, test, and remove virtual nodes directly from the Netdata UI using [dynamic configuration (dyncfg)](/docs/netdata-agent/configuration/dynamic-configuration-manager). Both methods configure a vnode that collectors can attach metrics to; SNMP mode first acquires a usable device identity. The Vnodes GUI path is available under the go.d plugin's dynamic configuration view. :::note @@ -146,7 +208,7 @@ In the Netdata UI, open the node's dynamic configuration view and look for the * ::: -The GUI form exposes `hostname`, `guid`, `labels`, and `stale_after` — the same fields as YAML, minus `name` which the Agent ignores: +The go.d GUI form selects `static` or `snmp` mode. The resource name entered when creating a vnode is its stable reference name. Static mode uses these fields: | Field | Required in the GUI | Description | |------------|---------------------|-------------------------------------------------------------------------------------------------------------------------------------| @@ -191,19 +253,39 @@ jobs: url: http://203.0.113.10:9182/metrics ``` -The `vnode` value must exactly match the vnode reference name. For YAML definitions, the reference name is always `hostname` and any explicit `name` is ignored; for GUI definitions, use the name assigned when creating the vnode. If that name is not registered, the job fails to start. +The `vnode` value must exactly match the vnode reference name. For static YAML definitions, use `hostname`; for SNMP YAML definitions, use the required `name`. For GUI definitions, use the resource name assigned when creating the vnode. An unknown name or an SNMP vnode awaiting its first usable identity prevents the job from starting; configured detection retries can start it once the identity is available. Several jobs can reference the same vnode. Its configured hostname and host labels govern output to its GUID within that plugin process, including collector-generated scopes using the same GUID. Job labels remain chart labels. Removing an unreferenced configured vnode lets generated contributors resume using their own host metadata. :::note -**SNMP** collectors behave differently: their `create_vnode: true` option auto-creates the vnode from the job configuration, so no separate vnode definition step is needed. +**SNMP** jobs can use the same `vnode: router` string reference. This takes precedence over `create_vnode`, including its default of `true`. Without a named reference, `create_vnode: true` retains the existing automatic vnode behavior and `local_vnode` configures the job-owned identity. Legacy inline `vnode` objects remain accepted. A named reference supplies identity only: keep the SNMP job's own `hostname`, credentials, and metric profiles configured. ::: +For a vnode created within an SNMP job, configure `local_vnode` instead of a named reference: + +```yaml +jobs: + - name: router_metrics + hostname: 192.0.2.1 + community: example-collector-community + create_vnode: true + local_vnode: + hostname: office-router + labels: + site: office +``` + +Existing SNMP configurations using `vnode: { hostname: ..., guid: ..., labels: ... }` keep working. +Dynamic configuration returns these settings under `local_vnode`, so the form can edit them without changing +which host receives metrics. Files are not rewritten. Do not specify both the legacy object and `local_vnode`. +A string `vnode` reference takes precedence over `create_vnode` and `local_vnode`; configure the central vnode to +change its host labels. + ### How Virtual Nodes Work -1. Define a vnode (YAML file or GUI) with a unique `hostname` and `guid` +1. Define a static vnode with a unique hostname and UUID, or an SNMP vnode with a stable name and acquisition connection 2. Configure the collector job with `vnode: ` to attach it 3. Metrics are tagged with the vnode's GUID instead of the Agent's Machine GUID 4. Cloud sees the vnode as a separate node in your Space @@ -455,33 +537,35 @@ For virtual nodes, see [Does renaming a virtual node change its identity?](#does
Does renaming a virtual node change its identity? -A virtual node's identity is determined by its **`guid`** field — not its `hostname` or `name`. The fields behave as follows: +A virtual node's identity is determined by its **UUID**. This is either explicitly configured as `guid` or, for an SNMP vnode without an override, derived from its exact configured address. The fields behave as follows: - **`guid`** — This is the vnode's identity. Changing it creates an entirely new node in Netdata Cloud. The old vnode's historical data remains under the old GUID but is no longer associated with the new one. -- **`hostname`** — This is used as the internal lookup key in the Agent and as the display name in dashboards. Changing `hostname` while keeping the same `guid` renames the display without creating a new node identity. -- **`name`** — The Agent ignores this field. When set to a value different from `hostname`, the Agent logs a warning and overrides it with `hostname`. +- **`hostname`** — The display name, and the reference key for static YAML definitions. Changing it without changing the UUID renames the display. Update job references too when renaming a static YAML definition. +- **`name`** — Required as the stable reference key for SNMP YAML definitions. Static YAML definitions ignore this field and use `hostname`; GUI definitions use their resource name. + +**To preserve data continuity when renaming a vnode**, edit `hostname` in the configuration source you used: its YAML file in the `vnodes/` directory of your [Netdata config directory](/docs/netdata-agent/configuration), or its [Vnodes GUI configuration](#creating-virtual-nodes-via-the-gui-dynamic-configuration). Keep any explicit `guid` unchanged. For an SNMP vnode with a derived UUID, keep the exact address unchanged too. -**To preserve data continuity when renaming a vnode**, change only the `hostname` field in its YAML file in the `vnodes/` directory of your [Netdata config directory](/docs/netdata-agent/configuration) and keep the `guid` unchanged. If a true identity change is needed, accept that historical data belongs to the old identity. +SNMP hostname overrides preserve the stable reference name. Changing an existing SNMP vnode's mode, address, context, or UUID requires a replacement vnode. Historical data belongs to the old UUID.
How do I find the UUID of my existing vnode? -The GUID for each virtual node is stored in its YAML configuration file in the `vnodes/` directory of your [Netdata config directory](/docs/netdata-agent/configuration). To look it up: +If the vnode has an explicit `guid`, that value is its UUID. Look it up in the configuration source: + +- **YAML-defined vnode:** read its `guid` in the `vnodes/` directory of your [Netdata config directory](/docs/netdata-agent/configuration). +- **GUI-created vnode:** open the node's dynamic configuration view, select **go.d → Vnodes**, and inspect the vnode's `guid`. GUI-created definitions are managed through dynamic configuration; they do not require a YAML file in `vnodes/`. + +To inspect YAML definitions: ```bash # Default path — adjust if your Netdata config directory differs. cat /etc/netdata/vnodes/* ``` -Each file contains a `guid` field that uniquely identifies the vnode: - -```yaml -- hostname: remote-server.example.com - guid: a1b2c3d4-e5f6-7890-abcd-ef1234567890 -``` +Static vnodes require an explicit `guid`. SNMP vnodes can omit it in either YAML or the GUI; their UUID is then derived from the exact `mode_snmp.address` string. The derived UUID is not written back into the authored configuration. It becomes visible with the vnode when an attached collector job publishes that node. -The `guid` value is the vnode's UUID. You do **not** need to query any internal database — the YAML configuration file is the authoritative source for the vnode GUID. See [Virtual Nodes](#virtual-nodes-vnodes) for the full configuration reference. +See [Virtual Nodes](#virtual-nodes-vnodes) for the full configuration reference.
diff --git a/docs/Network Performance Monitoring/Device Metrics/Configuration/SNMP Profile Format.mdx b/docs/Network Performance Monitoring/Device Metrics/Configuration/SNMP Profile Format.mdx index 2af2082f57..9a798701bb 100644 --- a/docs/Network Performance Monitoring/Device Metrics/Configuration/SNMP Profile Format.mdx +++ b/docs/Network Performance Monitoring/Device Metrics/Configuration/SNMP Profile Format.mdx @@ -797,8 +797,9 @@ ifHCInOctets.2 = 2048 - `.1`, `.2`, … are `row indexes` that identify the instance (e.g., interface #1, interface #2). - Each column (symbol) in the table has its own OID pattern but shares the same row indexes. -> Table metrics **must define at least one tag** (`metric_tags`) to identify each row. -> Without tags, only a single row can be emitted. +Table metrics need at least one resolved tag to be emitted; without tags, they are skipped. Use non-empty identifying +tags to distinguish rows, such as an interface name or a tag derived from the row index. The SNMP row index is not +added to the emitted series identity automatically. ```yaml metrics: diff --git a/ingest/generated_sidebar_order.json b/ingest/generated_sidebar_order.json index a3c0de9d87..be33bf7bff 100644 --- a/ingest/generated_sidebar_order.json +++ b/ingest/generated_sidebar_order.json @@ -2,7 +2,7 @@ "schema_version": 1, "source": "netdata/docs/.map/map.yaml", "source_sha256": "d0e76a8b2a2f7602b5832db7ff77c2169aab960a29ace7194a5e3422c113e997", - "source_corpus_sha256": "f50fe7d99408a952df372fe5b676bc7ede8ad9574f5f95a6ef22a80618f000c3", + "source_corpus_sha256": "b3837010cb9853939fb4eef3007f487c1f5ad921ac030fe324b98dd5ae1b1391", "order": [ { "parent_path": "Alerts & Notifications", @@ -1800,5 +1800,5 @@ "position": 180 } ], - "full_ingest_identity_sha256": "446e7382fac42a34aeee0c5de9432287bd47abd76421c4f78141cbd9f5b2388f" + "full_ingest_identity_sha256": "babb1c0f9ab4e764dc8f0e516faea3041cc53c6d3d4a84deacfc786e4ef2de92" } diff --git a/ingest/generated_sidebar_order.json.sha256 b/ingest/generated_sidebar_order.json.sha256 index 91c12b1c40..1d0582ff33 100644 --- a/ingest/generated_sidebar_order.json.sha256 +++ b/ingest/generated_sidebar_order.json.sha256 @@ -1 +1 @@ -c68a066c823a4d61fc4438fcadb7b3a856fe93c5163213c53cdc93ceaa1be402 generated_sidebar_order.json +4981a8490cc9075203d0bb6b6ed0795264d17f4a8956182bc31e82794e3ddde9 generated_sidebar_order.json