snmp3_set — Funktion · PHP-Referenz

Signatur

snmp3_set(string $hostname, string $security_name, string $security_level, string $auth_protocol, string $auth_passphrase, string $priv_protocol, string $priv_passphrase, string $object_id, string $type, mixed $value, int $timeout = -1, int $retries = 5): bool

Beschreibung

snmp3_set() sendet eine SNMP SET-Anfrage (Version 3) an einen entfernten Netzwerk-Host und schreibt den angegebenen Wert in das gewünschte SNMP-Objekt (OID). Im Gegensatz zu den einfacheren Varianten snmpset() und snmp2_set() unterstützt SNMPv3 starke Authentifizierung (MD5 oder SHA) sowie Verschlüsselung (DES oder AES), was es für sicherheitskritische Produktionsumgebungen geeignet macht.

Der Parameter security_level steuert, welche Sicherheitsdienste aktiv sind: noAuthNoPriv (weder Authentifizierung noch Verschlüsselung), authNoPriv (nur Authentifizierung) oder authPriv (Authentifizierung und Verschlüsselung). Je nach gewähltem Level müssen entsprechende Protokolle und Passphrasen angegeben werden.

Der Parameter type gibt den ASN.1-Typ des Wertes an. Gültige Werte sind unter anderem i (Integer), u (Unsigned Integer), s (String), x (Hex-String), d (Dezimal), n (Null), o (OID), t (Timeticks), a (IP-Adresse) und b (Bits). Der korrekte Typ muss zur MIB-Definition der OID passen.

Diese Funktion setzt voraus, dass die PHP-Extension ext/snmp kompiliert und aktiviert ist sowie die Net-SNMP-Bibliothek auf dem System installiert ist. Fehler (z. B. falsche Passphrase, nicht erreichbarer Host) führen zu einer PHP-Warnung und dem Rückgabewert false.

Parameter

Name	Typ	Default	Beschreibung
$hostname Pflicht	string		Hostname oder IP-Adresse des SNMP-Agenten. Optional kann ein Port mit Doppelpunkt angehängt werden, z. B. `192.168.1.1:161`.
$security_name Pflicht	string		Der SNMPv3-Benutzername (Security Name), wie er auf dem SNMP-Agenten konfiguriert ist.
$security_level Pflicht	string		Das Sicherheitsniveau: `noAuthNoPriv`, `authNoPriv` oder `authPriv`.
$auth_protocol Pflicht	string		Das Authentifizierungsprotokoll: `MD5` oder `SHA`. Wird ignoriert, wenn `security_level` `noAuthNoPriv` ist.
$auth_passphrase Pflicht	string		Die Passphrase für die Authentifizierung. Muss mindestens 8 Zeichen lang sein. Wird ignoriert, wenn kein Auth-Level gesetzt ist.
$priv_protocol Pflicht	string		Das Verschlüsselungsprotokoll: `DES` oder `AES`. Wird nur bei `authPriv` ausgewertet.
$priv_passphrase Pflicht	string		Die Passphrase für die Verschlüsselung. Muss mindestens 8 Zeichen lang sein. Wird nur bei `authPriv` ausgewertet.
$object_id Pflicht	string		Die OID des SNMP-Objekts, das gesetzt werden soll, z. B. `.1.3.6.1.2.1.1.6.0` oder ein symbolischer MIB-Name.
$type Pflicht	string		ASN.1-Typkürzel des Wertes: `i` (Integer), `u` (Unsigned), `s` (String), `x` (Hex-String), `d` (Dezimal), `n` (Null), `o` (OID), `t` (Timeticks), `a` (IP-Adresse), `b` (Bits).
$value Pflicht	mixed		Der zu setzende Wert. Muss dem angegebenen `type` entsprechen.
$timeout	int	-1	Timeout in Mikrosekunden. `-1` verwendet den Systemstandard.
$retries	int	5	Anzahl der Wiederholungsversuche bei Timeout.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn der Wert erfolgreich gesetzt wurde. Bei einem Fehler (z. B. falscher Typ, nicht erreichbarer Host, Authentifizierungsfehler) wird false zurückgegeben und eine PHP-Warnung ausgelöst.

Beispiele

Systemstandort per SNMPv3 mit Authentifizierung und Verschlüsselung setzen

<?php
$host       = '192.168.1.10';
$user       = 'snmpv3user';
$secLevel   = 'authPriv';
$authProto  = 'SHA';
$authPass   = 'meinAuthPasswort';
$privProto  = 'AES';
$privPass   = 'meinPrivPasswort';
$oid        = '.1.3.6.1.2.1.1.6.0'; // sysLocation

$result = snmp3_set(
    $host,
    $user,
    $secLevel,
    $authProto,
    $authPass,
    $privProto,
    $privPass,
    $oid,
    's',
    'Serverraum EG, Rack 3'
);

if ($result) {
    echo "Systemstandort erfolgreich gesetzt.\n";
} else {
    echo "Fehler beim Setzen des Systemstandorts.\n";
}

Systemstandort erfolgreich gesetzt.

Integer-Wert ohne Verschlüsselung setzen (authNoPriv)

<?php
// Nur Authentifizierung, keine Verschlüsselung
$result = snmp3_set(
    'switch.example.com',
    'adminuser',
    'authNoPriv',
    'MD5',
    'authPassphrase123',
    '',   // priv_protocol leer bei authNoPriv
    '',   // priv_passphrase leer bei authNoPriv
    '.1.3.6.1.2.1.1.5.0', // sysName
    's',
    'neuer-switch-name'
);

var_dump($result);

bool(true)

// Wichtig · Fallstricke

Sicherheitshinweis: Passphrasen sollten niemals im Klartext im Quellcode stehen. Nutze Umgebungsvariablen oder verschlüsselte Konfigurationsdateien, um Zugangsdaten zu speichern.

Der security_level noAuthNoPriv bietet keinerlei Sicherheit und sollte in Produktionsumgebungen vermieden werden. Für maximale Sicherheit ist authPriv mit SHA und AES zu empfehlen.

Stelle sicher, dass der SNMP-Community-String bzw. der SNMPv3-Benutzer auf dem Agenten Schreibzugriff auf die gewünschte OID hat, da SET-Operationen häufig separat von GET-Operationen berechtigt werden.

Die Funktion erfordert, dass die PHP-Erweiterung ext/snmp aktiviert ist (extension=snmp in der php.ini).

Siehe auch

snmp3_get snmp3_getnext snmp3_walk snmpset snmp2_set snmp_set_valueretrieval