{"id":13582435,"url":"https://github.com/prometheus/snmp_exporter","last_synced_at":"2025-05-06T02:54:48.229Z","repository":{"id":27699145,"uuid":"31185891","full_name":"prometheus/snmp_exporter","owner":"prometheus","description":"SNMP Exporter for Prometheus","archived":false,"fork":false,"pushed_at":"2025-05-04T17:48:34.000Z","size":10688,"stargazers_count":1850,"open_issues_count":90,"forks_count":664,"subscribers_count":47,"default_branch":"main","last_synced_at":"2025-05-04T18:20:40.663Z","etag":null,"topics":["metrics","mib","monitoring","prometheus","prometheus-exporter","snmp"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/prometheus.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2015-02-22T23:24:16.000Z","updated_at":"2025-05-04T17:35:21.000Z","dependencies_parsed_at":"2023-10-03T14:26:03.309Z","dependency_job_id":"becf478a-3ef9-414a-ae1a-67337bf93e4f","html_url":"https://github.com/prometheus/snmp_exporter","commit_stats":{"total_commits":629,"total_committers":136,"mean_commits":4.625,"dds":0.7376788553259142,"last_synced_commit":"e9a9866daba1ac3c0515a1f4974ab6255bfc9acd"},"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prometheus%2Fsnmp_exporter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prometheus%2Fsnmp_exporter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prometheus%2Fsnmp_exporter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prometheus%2Fsnmp_exporter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/prometheus","download_url":"https://codeload.github.com/prometheus/snmp_exporter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252612465,"owners_count":21776254,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["metrics","mib","monitoring","prometheus","prometheus-exporter","snmp"],"created_at":"2024-08-01T15:02:42.489Z","updated_at":"2025-05-06T02:54:48.204Z","avatar_url":"https://github.com/prometheus.png","language":"Go","funding_links":[],"categories":["Misc","Go","monitoring","Tools","Prometheus-Exporter","Exporters"],"sub_categories":["CLIs","Other monitoring systems"],"readme":"# Prometheus SNMP Exporter\n\nThis exporter is the recommended way to expose SNMP data in a format which\nPrometheus can ingest.\n\nTo simply get started, it's recommended to use the `if_mib` module with\nswitches, access points, or routers using the `public_v2` auth module,\nwhich should be a read-only access community on the target device.\n\nNote, community strings in SNMP are not considered secrets, as they are sent\nunencrypted in SNMP v1 and v2c. For secure access, SNMP v3 is required.\n\n# Concepts\n\nWhile SNMP uses a hierarchical data structure and Prometheus uses an\nn-dimensional matrix, the two systems map perfectly, and without the need\nto walk through data by hand. `snmp_exporter` maps the data for you.\n\n## Prometheus\n\nPrometheus is able to map SNMP index instances to labels. For example, the `ifEntry` specifies an INDEX of  `ifIndex`. This becomes the `ifIndex` label in Prometheus.\n\nIf an SNMP entry has multiple index values, each value is mapped to a separate Prometheus label.\n\n## SNMP\n\nSNMP is structured in OID trees, described by MIBs. OID subtrees have the same\norder across different locations in the tree. The order under\n`1.3.6.1.2.1.2.2.1.1` (`ifIndex`) is the same as in `1.3.6.1.2.1.2.2.1.2`\n(`ifDescr`), `1.3.6.1.2.1.31.1.1.1.10` (`ifHCOutOctets`), etc. The numbers are\nOIDs, the names in parentheses are the names from a MIB, in this case\n[IF-MIB](http://www.oidview.com/mibs/0/IF-MIB.html).\n\n## Mapping\n\nGiven a device with an interface at number 2, a partial `snmpwalk` return looks\nlike:\n\n```\n1.3.6.1.2.1.2.2.1.1.2 = INTEGER: 2         # ifIndex for '2' is literally just '2'\n1.3.6.1.2.1.2.2.1.2.2 = STRING: \"eth0\"     # ifDescr\n1.3.6.1.2.1.31.1.1.1.1.2 = STRING: \"eth0\"  # IfName\n1.3.6.1.2.1.31.1.1.1.10.2 = INTEGER: 1000  # ifHCOutOctets, 1000 bytes\n1.3.6.1.2.1.31.1.1.1.18.2 = STRING: \"\"     # ifAlias\n```\n\n`snmp_exporter` combines all of this data into:\n\n```\nifHCOutOctets{ifAlias=\"\",ifDescr=\"eth0\",ifIndex=\"2\",ifName=\"eth0\"} 1000\n```\n\n# Scaling\n\nA single instance of `snmp_exporter` can be run for thousands of devices.\n\n# Usage\n\n## Installation\n\nBinaries can be downloaded from the [Github\nreleases](https://github.com/prometheus/snmp_exporter/releases) page and need no\nspecial installation.\n\nWe also provide a sample [systemd unit file](examples/systemd/snmp_exporter.service).\n\n## Running\n\nStart `snmp_exporter` as a daemon or from CLI:\n\n```sh\n./snmp_exporter\n```\n\nVisit \u003chttp://localhost:9116/snmp?target=192.0.0.8\u003e where `192.0.0.8` is the IP or\nFQDN of the SNMP device to get metrics from. Note that this will use the default transport (`udp`),\ndefault port (`161`), default auth (`public_v2`) and default module (`if_mib`). The auth and module\nmust be defined in the `snmp.yml` file.\n\nFor example, if you have an auth named `my_secure_v3` for walking `ddwrt`, the URL would look like\n\u003chttp://localhost:9116/snmp?auth=my_secure_v3\u0026module=ddwrt\u0026target=192.0.0.8\u003e.\n\nTo configure a different transport and/or port, use the syntax `[transport://]host[:port]`.\n\nFor example, to scrape a device using `tcp` on port `1161`, the URL would look like\n\u003chttp://localhost:9116/snmp?auth=my_secure_v3\u0026module=ddwrt\u0026target=tcp%3A%2F%2F192.0.0.8%3A1161\u003e.\n\nNote that [URL encoding](https://en.wikipedia.org/wiki/URL_encoding) should be used for `target` due\nto the `:` and `/` characters. Prometheus encodes query parameters automatically and manual encoding\nis not necessary within the Prometheus configuration file.\n\nMetrics concerning the operation of the exporter itself are available at the\nendpoint \u003chttp://localhost:9116/metrics\u003e.\n\nIt is possible to supply an optional `snmp_context` parameter in the URL, like this:\n\u003chttp://localhost:9116/snmp?auth=my_secure_v3\u0026module=ddwrt\u0026target=192.0.0.8\u0026snmp_context=vrf-mgmt\u003e\nThe `snmp_context` parameter in the URL would override the `context_name` parameter in the `snmp.yml` file.\n\n## Multi-Module Handling\nThe multi-module functionality allows you to specify multiple modules, enabling the retrieval of information from several modules in a single scrape.\nThe concurrency can be specified using the snmp-exporter option `--snmp.module-concurrency` (the default is 1).\n\nNote: This implementation does not perform any de-duplication of walks between different modules.\n\nThere are two ways to specify multiple modules. You can either separate them with a comma or define multiple params_module.\nThe URLs would look like this:\n\nFor comma separation:\n```\nhttp://localhost:9116/snmp?module=if_mib,arista_sw\u0026target=192.0.0.8\n```\n\nFor multiple params_module:\n```\nhttp://localhost:9116/snmp?module=if_mib\u0026module=arista_sw\u0026target=192.0.0.8\n```\n\nPrometheus Example:\n```YAML\n\n  - job_name: 'my'\n    params:\n      module: \n        - if_mib\n        - synology\n        - ucd_la_table\n```\n\n## Configuration\n\nThe default configuration file name is `snmp.yml` and should not be edited\nby hand. If you need to change it, see\n[Generating configuration](#generating-configuration).\n\nThe default `snmp.yml` file covers a variety of common hardware walking them\nusing SNMP v2 GETBULK.\n\nThe `--config.file` parameter can be used multiple times to load more than one file.\nIt also supports [glob filename matching](https://pkg.go.dev/path/filepath#Glob), e.g. `snmp*.yml`.\n\nThe `--config.expand-environment-variables` parameter allows passing environment variables into some fields of the configuration file. The `username`, `password` \u0026 `priv_password` fields in the auths section are supported. Defaults to disabled.\n\nDuplicate `module` or `auth` entries are treated as invalid and can not be loaded.\n\n## Prometheus Configuration\n\nThe URL params `target`, `auth`, and `module` can be controlled through relabelling.\n\nExample config:\n```YAML\nscrape_configs:\n  - job_name: 'snmp'\n    static_configs:\n      - targets:\n        - 192.168.1.2  # SNMP device.\n        - switch.local # SNMP device.\n        - tcp://192.168.1.3:1161  # SNMP device using TCP transport and custom port.\n    metrics_path: /snmp\n    params:\n      auth: [public_v2]\n      module: [if_mib]\n    relabel_configs:\n      - source_labels: [__address__]\n        target_label: __param_target\n      - source_labels: [__param_target]\n        target_label: instance\n      - target_label: __address__\n        replacement: 127.0.0.1:9116  # The SNMP exporter's real hostname:port.\n\n  # Global exporter-level metrics\n  - job_name: 'snmp_exporter'\n    static_configs:\n      - targets: ['localhost:9116']\n```\n\nYou could pass `username`, `password` \u0026 `priv_password` via environment variables of your choice in below format. \nIf the variables exist in the environment, they are resolved on the fly otherwise the string in the config file is passed as-is.\n\nThis requires the `--config.expand-environment-variables` flag be set.\n\n```YAML\nauths:\n  example_with_envs:\n    community: mysecret\n    security_level: SomethingReadOnly\n    username: ${ARISTA_USERNAME}\n    password: ${ARISTA_PASSWORD}\n    auth_protocol: SHA256\n    priv_protocol: AES\n    priv_password: ${ARISTA_PRIV_PASSWORD}\n```\n\nSimilarly to [blackbox_exporter](https://github.com/prometheus/blackbox_exporter),\n`snmp_exporter` is meant to run on a few central machines and can be thought of\nlike a \"Prometheus proxy\".\n\n### TLS and basic authentication\n\nThe SNMP Exporter supports TLS and basic authentication. This enables better\ncontrol of the various HTTP endpoints.\n\nTo use TLS and/or basic authentication, you need to pass a configuration file\nusing the `--web.config.file` parameter. The format of the file is described\n[in the exporter-toolkit repository](https://github.com/prometheus/exporter-toolkit/blob/master/docs/web-configuration.md).\n\nNote that the TLS and basic authentication settings affect all HTTP endpoints:\n/metrics for scraping, /snmp for scraping SNMP devices, and the web UI.\n\n### Generating configuration\n\nMost use cases should be covered by our [default configuration](snmp.yml).\nIf you need to generate your own configuration from MIBs, you can use the\n[generator](generator/).\n\nUse the generator if you need to customize which objects are walked or use\nnon-public MIBs.\n\n## Large counter value handling\n\nIn order to provide accurate counters for large Counter64 values, the exporter\nwill automatically wrap the value every 2^53 to avoid 64-bit float rounding.\nPrometheus handles this gracefully for you and you will not notice any negative\neffects.\n\nIf you need to disable this feature for non-Prometheus systems, use the\ncommand line flag `--no-snmp.wrap-large-counters`.\n\n# Once you have it running\n\nIt can be opaque to get started with all this, but in our own experience,\nsnmp_exporter is honestly the best way to interact with SNMP. To make it\neasier for others, please consider contributing back your configurations to\nus.\n`snmp.yml` config should be accompanied by generator config.\nFor your dashboard, alerts, and recording rules, please consider\ncontributing them to \u003chttps://github.com/prometheus/snmp_exporter/tree/main/snmp-mixin\u003e.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprometheus%2Fsnmp_exporter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprometheus%2Fsnmp_exporter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprometheus%2Fsnmp_exporter/lists"}