> For the complete documentation index, see [llms.txt](https://documentation.ocsinventory-ng.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.ocsinventory-ng.org/administrator-docs/network-discovery/snmp.md).

# SNMP

Availability of SNMP data within the OCS webconsole will require a [#snmp-scanner](#snmp-scanner "mention") to be installed and configured.

The SNMP scanner can operate as a standalone tool (offline mode) or communicate directly with an OCS server (online mode).

***

## SNMP Scanner

The SNMP Scanner is a tool designed to scan networks and collect device information using the SNMP protocol.\
It always uses a **hardcoded base inventory** (matching generic OIDs) to retrieve information.\
If a template is available, the scanner performs an **advanced scan** using the template retrieved from the OCS server.

### Available scan modes

The scanner can operate in two modes: **online** and **offline**.

{% hint style="info" %}
If the scanner is unable to communicate with the OCS server, it will switch to **offline** mode automatically.
{% endhint %}

{% tabs %}
{% tab title="Online" %}
In online mode, the scanner queries the OCS server to check whether a device has already been scanned, and if so, whether a template is defined for it.\
If a template is available, the scanner performs an advanced scan using that template, and then sends the inventory data back to the server.
{% endtab %}

{% tab title="Offline" %}
In **offline** mode, the scanner only uses the base template and does not query the OCS server at all, inventory data will be stored in individual files in the `local_inventory_dir` directory and local configuration will be used.
{% endtab %}
{% endtabs %}

### Scanning process

#### **Supported SNMP versions**

The scanner supports **SNMPv1**, **SNMPv2c**, and **SNMPv3**.\
The version used is determined by the configuration file `configs.json` or by the configuration retrieved from the **OCS** server.

#### **Basic scan**

The basic scan uses **generic OIDs** to populate the [**base inventory**](/user-docs/asset-management/inventory-and-templates.md#base-inventory) **fields.** The goal is to retrieve as much data as possible from devices, regardless of type.\
It is performed for **all devices**, whether or not a custom template exists.

#### **Advanced scan**

If a template exists for a device, an advanced scan is performed using OIDs defined in the template file retrieved from the OCS server.\
The template contains a list of OIDs required to enrich the scan.\
The scanner uses these OIDs to retrieve corresponding device values.

### SNMP scanner installation

{% hint style="info" %}
The SNMP scanner is published on the same official OCS Inventory repositories as the rest of the v3 components. If the host already has the repository configured, skip straight to the `apt install` / `dnf install` step below.
{% endhint %}

{% tabs %}
{% tab title="Debian / Ubuntu (.deb)" %}
**Requirements:** Debian 12 (bookworm) or later, or an Ubuntu release shipping Python ≥ 3.9.

Add the repository (skip if already configured on the host):

```sh
curl -fsSL https://deb-v3.ocsinventory-ng.org/repo-signing-key.gpg | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/ocs-archive-keyring.gpg
echo "deb https://deb-v3.ocsinventory-ng.org/ <distribution_codename> main" | sudo tee /etc/apt/sources.list.d/ocsinventory.list
sudo apt update
```

Replace `<distribution_codename>` with your system's codename (Debian: `bookworm`, `trixie`; Ubuntu: `jammy`, `noble`, `plucky`).

Then install the package:

```bash
sudo apt install ocsinventory-snmp-scanner
```

**Uninstalling:**

```bash
sudo apt remove ocsinventory-snmp-scanner   # keeps configuration, logs and the ocssnmp user
sudo apt purge  ocsinventory-snmp-scanner   # also removes configuration, logs, offline inventory files and the ocssnmp user
```

{% endtab %}

{% tab title="RHEL / Rocky / Fedora (.rpm)" %}
**Requirements:** Fedora, RHEL 9+, Rocky Linux 9+ or an equivalent, shipping Python ≥ 3.9.

Add the repository (skip if already configured on the host) — this installs the release package that configures the DNF/YUM repository and imports the signing key:

```bash
sudo dnf install -y https://rpm-v3.ocsinventory-ng.org/rpm/ocsinventory-release-latest.[elX|fcXX].noarch.rpm
```

Replace `[elX|fcXX]` with your OS version (Enterprise Linux: `el9`, `el10`; Fedora: `fc42`, `fc43`, `fc44`).

Then install the package:

```bash
sudo dnf install -y ocsinventory-snmp-scanner
```

**Uninstalling:**

```bash
sudo dnf remove ocsinventory-snmp-scanner
```

This stops and disables the service and timer, and removes the scanner's application files, logs, offline inventory data, and the `ocssnmp` system user.
{% endtab %}
{% endtabs %}

#### What the package installs

| Purpose                                         | Path                                                                                        |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Application code                                | `/usr/share/ocsinventory-snmp-scanner/`                                                     |
| Python virtual environment                      | `/usr/lib/ocsinventory-snmp-scanner/venv/`                                                  |
| Configuration (`scanner.conf`, `configs.json`)  | `/etc/ocsinventory-snmp-scanner/`                                                           |
| Logs                                            | `/var/log/ocsinventory-snmp-scanner/snmp_scanner.log` (also available through `journalctl`) |
| Offline inventory files (`local_inventory_dir`) | `/var/lib/ocsinventory-snmp-scanner/files/`                                                 |
| MIBs cache (`mibs_dir`)                         | `/var/lib/ocsinventory-snmp-scanner/mibs/`                                                  |
| systemd units                                   | `ocsinventory-snmp-scanner.service`, `ocsinventory-snmp-scanner.timer`                      |

{% hint style="info" %}
A dedicated, unprivileged system user (`ocssnmp`) owns the scanner's logs and data and runs the service.
{% endhint %}

## SNMP configuration

{% hint style="info" %}
Configuration retrieved from the OCS server overrides any local configuration file.\
To run the scanner with its local configuration, switch to **offline** mode for a debug run or update the configuration on the OCS server temporarily.
{% endhint %}

{% tabs %}
{% tab title="Online" %}

### Enabling SNMP scanning

Navigate to **Configurations** **➜ Networks ➜ SNMP.**

On the default tab **General**, at the top, enabled the SNMP option using the on/off switch.

### User

A dedicated [user](/administrator-docs/server-setup/configuration/basics/users.md#users-and-permissions) must be created on the OCS web console with appropriate [permissions](/administrator-docs/server-setup/configuration/basics/groups-and-permissions.md). The user must have the following permissions:

* View : `Inventory - Asset`, `Templates`, `SNMP Scanner`, `Configuration - General`
* Add : `Inventory - Asset`, `SNMP Scanner`
* Change : `Inventory - Asset`, `SNMP Scanner`
* Delete : `Inventory - Asset`

### Communities

#### To create a community:

{% stepper %}
{% step %}
Navigate to **Configurations** **➜ Networks ➜ SNMP.**
{% endstep %}

{% step %}
On the **General** tab, locate the **Communities** section.
{% endstep %}

{% step %}
Click the **Add an SNMP community** button.
{% endstep %}

{% step %}
Fill the form.

* **Name**: name of the community
* **Version**: SNMP version to use (v1, v2c or v3)
* **User**: SNMP user to use (only for SNMPv3)
* **Password**: SNMP password to use (only for SNMPv3)
* **Level**: Authentication level to use (only for SNMPv3)
* **Authentication** **protocol**: Authentication protocol to use (only for SNMPv3)
* **Privacy** **protocol**: Privacy protocol to use (only for SNMPv3)
* **Privacy** **password**: Privacy password to use (only for SNMPv3)
* **Retries**: number of retries to perform when scanning a device
* **Timeout**: timeout in seconds to wait for a response from a device
* **Subnets**: list of subnets to scan, in CIDR notation, comma separated. These will be matched against the Scanner's `subnets` field to determine if the scanner should use this configuration to scan a device.
  {% endstep %}

{% step %}
Click **Add**.
{% endstep %}
{% endstepper %}

### Scanner configuration

The scanner configuration will be read from the `config/scanner.conf` file:

```
[auth] # not used in offline mode
ocs_user = ocssnmp
ocs_password = ocssnmp

[api] # not used in offline mode
ocs_base_url = http://ocsinventory-server:8000
# path to a PEM certificate file, used in addition to the system trust store
# when the server certificate cannot be validated against it (private CA,
# self-signed). Leave empty to rely on the system trust store alone
certificate =
# Set to true to skip certificate validation entirely
bypass_certificate = false


[scanner]
scanner_mode = ONLINE # either OFFLINE or ONLINE
local_inventory_dir = files # path where the snmp inventory files should be written in OFFLINE mode
targeted_subnets = 172.18.25.0/24,172.18.15.0/24
log_level = DEBUG
name = d9b95863-9f61-409b-ba68-test # not used in offline mode
mibs_dir = /path/to/mibs/ # optional path to MIBs directory
server_logging_enabled = true # not used in offline mode, will send inventory logs to the server if enabled
server_log_level = WARNING
```

### Scanner registration

Scanner registration is automatic when running in [**online**](#online) mode.\
The scanner creates its own instance in OCS during its first run.

The entry is created using:

* **name** from the local `configs.json`
* **subnets** from the local `configs.json`

The **name** is the scanner’s unique name.\
The **subnets** field lists the networks the scanner scans.

Once registered, assign a [**community**](#communities) to the scanner using the OCS web console:

{% stepper %}
{% step %}
Navigate to **Configuration → Networks → SNMP.**
{% endstep %}

{% step %}
Switch to the **Scanner** tab.
{% endstep %}

{% step %}
Locate the scanner entry you want to edit and click the pencil icon in the Actions column.
{% endstep %}

{% step %}
Edit the form:

* Name
* IP address
* Networks: comma-separated list of subnets the scanner should scan, in CIDR notation.
* Notes
* Communities: assign communities to this scanner using the dropdown.
  {% endstep %}

{% step %}
Click **Add**.
{% endstep %}
{% endstepper %}

### Template example

By default, a generic SNMP template is available.\
A default [**Rule**](/administrator-docs/server-setup/configuration/advanced/managing-rules.md) automatically assigns it to every SNMP asset.

The template can be found under **Configuration → Networks → SNMP → Templates.**
{% endtab %}

{% tab title="Offline" %}

### Communities

In **offline** mode, SNMP communities are defined locally in the `configs.json` file. The scanner reads this file at startup and uses the configuration entries to determine how each subnet should be scanned.

Here is an example of the `configs.json` content:

```json
[
	{
		"id": 3,
		"name": "public",
		"version": "2c",
		"user": "",
		"auth_level": "noAuthNoPriv",
		"password": "",
		"auth_protocol": "MD5",
		"priv_protocol": "DES",
		"priv_password": "mellon",
		"retries": 1,
		"timeout": 1,
		"subnets": [
			"172.18.15.0/24"
		]
	}
]
```

### Scanner configuration

The scanner configuration will be read from the `config/scanner.conf` file:

```
[auth] # not used in offline mode
ocs_user = ocssnmp
ocs_password = ocssnmp

[api] # not used in offline mode
ocs_base_url = http://ocsinventory-server:8000
# path to a PEM certificate file, used in addition to the system trust store
# when the server certificate cannot be validated against it (private CA,
# self-signed). Leave empty to rely on the system trust store alone
certificate =
# Set to true to skip certificate validation entirely
bypass_certificate = false


[scanner]
scanner_mode = ONLINE # either OFFLINE or ONLINE
local_inventory_dir = files # path where the snmp inventory files should be written in OFFLINE mode
targeted_subnets = 172.18.25.0/24,172.18.15.0/24
log_level = DEBUG
name = d9b95863-9f61-409b-ba68-test # not used in offline mode
mibs_dir = /path/to/mibs/ # optional path to MIBs directory
server_logging_enabled = true # not used in offline mode, will send inventory logs to the server if enabled
server_log_level = WARNING
```

### Scanner registration

Registering a scanner is optional in offline (standalone) mode but can be done manually from the OCS web console for easy of management, see [registering an SNMP scanner](#scanner-registration).
{% endtab %}
{% endtabs %}

## Running the scanner

**Run once, to test your configuration:**

```bash
sudo systemctl start ocsinventory-snmp-scanner.service
```

Check the outcome:

```bash
sudo systemctl status ocsinventory-snmp-scanner.service
sudo journalctl -u ocsinventory-snmp-scanner.service
```

**Schedule recurring scans:**

The package ships a weekly timer, disabled by default:

```bash
sudo systemctl enable --now ocsinventory-snmp-scanner.timer
```

This runs a scan once a week, with up to an hour of random delay (so a whole fleet installed from the same image doesn't scan at the exact same instant), and automatically catches up on a missed run if the machine was off at the scheduled time. Check the next scheduled run with:

```bash
systemctl list-timers ocsinventory-snmp-scanner.timer
```

To change the frequency, override the timer instead of editing the shipped unit file directly:

```bash
sudo systemctl edit ocsinventory-snmp-scanner.timer
```

## Results

{% tabs %}
{% tab title="Online" %}
In the online mode, the results will be displayed under the **Inventory** **→** **General** **→** **Assets** page, along non-SNMP devices.
{% endtab %}

{% tab title="Offline" %}
In **offline** mode, the inventories generated during the SNMP scan will be stored under the path defined by the local configuration option `local_inventory_dir`.
{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://documentation.ocsinventory-ng.org/administrator-docs/network-discovery/snmp.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.