snmp3_get — Funktion · PHP-Referenz

Signatur

snmp3_get(string $hostname, string $security_name, string $security_level, string $auth_protocol, string $auth_passphrase, string $priv_protocol, string $priv_passphrase, string $object_id, int $timeout = -1, int $retries = -1): mixed

Beschreibung

snmp3_get() sendet eine SNMPv3-GET-Anfrage an einen SNMP-Agenten und gibt den Wert des angegebenen Objektbezeichners (OID) zurück. SNMPv3 bietet gegenüber SNMPv1/v2c deutlich verbesserte Sicherheit durch Authentifizierung und optionale Datenverschlüsselung (Privacy).

Die Funktion eignet sich überall dort, wo sicherheitskritische Netzwerkinfrastruktur abgefragt werden muss – etwa Router, Switches, USV-Anlagen oder Server – und wo SNMPv1/v2c aufgrund fehlender Verschlüsselung nicht ausreicht. Typische Anwendungsfälle sind Monitoring-Systeme und Netzwerk-Management-Tools.

Für den Parameter security_level stehen die Werte noAuthNoPriv, authNoPriv und authPriv zur Verfügung. Als Authentifizierungsprotokoll (auth_protocol) werden MD5 und SHA unterstützt, als Privacy-Protokoll (priv_protocol) DES und AES.

Die Funktion setzt eine korrekt installierte Net-SNMP-Bibliothek auf dem System voraus und muss beim Kompilieren von PHP explizit aktiviert werden (--with-snmp).

Parameter

Name	Typ	Default	Beschreibung
$hostname Pflicht	string		Hostname oder IP-Adresse des SNMP-Agenten. Optionally kann ein Port mit Doppelpunkt angehängt werden, z. B. `192.168.1.1:161`.
$security_name Pflicht	string		Der SNMPv3-Benutzername (Security Name), der auf dem SNMP-Agenten konfiguriert ist.
$security_level Pflicht	string		Sicherheitsstufe der Verbindung. Gültige Werte: `noAuthNoPriv` (keine Auth, keine Verschlüsselung), `authNoPriv` (nur Auth), `authPriv` (Auth + Verschlüsselung).
$auth_protocol Pflicht	string		Authentifizierungsprotokoll. Gültige Werte: `MD5` oder `SHA`. Bei `noAuthNoPriv` kann ein leerer String übergeben werden.
$auth_passphrase Pflicht	string		Passphrase für die Authentifizierung. Muss mindestens 8 Zeichen lang sein. Bei `noAuthNoPriv` kann ein leerer String übergeben werden.
$priv_protocol Pflicht	string		Verschlüsselungsprotokoll für den Privacy-Modus. Gültige Werte: `DES` oder `AES`. Bei `authNoPriv` oder `noAuthNoPriv` kann ein leerer String übergeben werden.
$priv_passphrase Pflicht	string		Passphrase für die Privacy-Verschlüsselung. Muss mindestens 8 Zeichen lang sein. Bei `authNoPriv` oder `noAuthNoPriv` kann ein leerer String übergeben werden.
$object_id Pflicht	string		Der OID des abzufragenden SNMP-Objekts, z. B. `.1.3.6.1.2.1.1.1.0` für den Systembeschreibungs-String (sysDescr).
$timeout	int	-1	Timeout in Mikrosekunden. `-1` verwendet den Standardwert der Net-SNMP-Bibliothek.
$retries	int	-1	Anzahl der Wiederholungsversuche bei Timeout. `-1` verwendet den Standardwert der Net-SNMP-Bibliothek.

Rückgabewert

Typ

mixed

Beschreibung

Gibt den Wert des abgefragten SNMP-Objekts als string zurück. Bei einem Fehler (z. B. nicht erreichbarer Host, falsche Zugangsdaten) wird false zurückgegeben und eine PHP-Warnung ausgelöst.

Beispiele

Systembeschreibung eines Netzwerkgeräts abrufen (authPriv)

<?php
// Systembeschreibung (sysDescr) eines Switches mit SNMPv3 auslesen
$hostname       = '192.168.1.1';
$security_name  = 'snmpv3user';
$security_level = 'authPriv';
$auth_protocol  = 'SHA';
$auth_pass      = 'auth_secret_pass';
$priv_protocol  = 'AES';
$priv_pass      = 'priv_secret_pass';
$oid            = '.1.3.6.1.2.1.1.1.0'; // sysDescr

$result = snmp3_get(
    $hostname,
    $security_name,
    $security_level,
    $auth_protocol,
    $auth_pass,
    $priv_protocol,
    $priv_pass,
    $oid
);

if ($result === false) {
    echo 'Fehler beim Abrufen des SNMP-Objekts.';
} else {
    echo 'Systembeschreibung: ' . $result;
}

Systembeschreibung: STRING: Cisco IOS Software, Version 15.2(4)M7

Verbindung ohne Authentifizierung (noAuthNoPriv) für Testzwecke

<?php
// SNMPv3 ohne Auth und Privacy – nur für Testzwecke in isolierten Netzwerken!
$result = snmp3_get(
    '10.0.0.1',
    'publicv3user',
    'noAuthNoPriv',
    '',   // kein Auth-Protokoll
    '',   // keine Auth-Passphrase
    '',   // kein Priv-Protokoll
    '',   // keine Priv-Passphrase
    'sysName.0'
);

if ($result !== false) {
    echo 'Gerätename: ' . $result;
} else {
    echo 'SNMP-Abfrage fehlgeschlagen.';
}

Gerätename: STRING: core-switch-01

// Wichtig · Fallstricke

Sicherheitshinweis: Verwenden Sie in Produktivumgebungen grundsätzlich den Security Level authPriv mit starken Passwörtern, um Man-in-the-Middle-Angriffe und das Abhören von SNMP-Kommunikation zu verhindern. noAuthNoPriv und authNoPriv sind nur für isolierte Testumgebungen geeignet.

MD5 und DES gelten als kryptografisch schwach. Bevorzugen Sie SHA als Authentifizierungsprotokoll und AES als Privacy-Protokoll, sofern das Zielgerät dies unterstützt.

Passwörter für Auth und Privacy sollten mindestens 8 Zeichen umfassen (SNMP-Anforderung). Kürzere Passwörter führen zu einem Fehler.

Die Funktion gibt bei Fehlern false zurück und erzeugt gleichzeitig eine PHP-Warnung. Mit dem Fehlerunterdrückungs-Operator @ kann die Warnung unterdrückt werden, was jedoch generell nicht empfohlen wird – besser ist die Nutzung von set_error_handler() oder die Prüfung des Rückgabewerts.

Siehe auch

snmp3_set snmp3_walk snmp3_getnext snmp2_get snmpget snmp_set_valueretrieval