search

calmh / node-snmp-native

Native Javascript SNMP library for Node.js
MIT License
252 stars 66 forks source link

readme 

                                                             __
                                                            /\ \__  __
  ____    ___     ___ ___   _____              ___      __  \ \ ,_\/\_\   __  __     __
 /',__\ /' _ `\ /' __` __`\/\ '__`\  _______ /' _ `\  /'__`\ \ \ \/\/\ \ /\ \/\ \  /'__`\
/\__, `\/\ \/\ \/\ \/\ \/\ \ \ \L\ \/\______\/\ \/\ \/\ \L\.\_\ \ \_\ \ \\ \ \_/ |/\  __/
\/\____/\ \_\ \_\ \_\ \_\ \_\ \ ,__/\/______/\ \_\ \_\ \__/.\_\\ \__\\ \_\\ \___/ \ \____\
 \/___/  \/_/\/_/\/_/\/_/\/_/\ \ \/           \/_/\/_/\/__/\/_/ \/__/ \/_/ \/__/   \/____/
                              \ \_\
                               \/_/

snmp-native Build Status

This is a native SNMP library for Node.js. The purpose is to provide enough functionality to perform large scale monitoring of network equipment. Current features towards this end are:

It specifically does not include:

It's optimized for polling tens of thousands of counters on hundreds or thousands of hosts in a parallell manner. This is known to work (although performance might be limited by less than optimal SNMP agent implementations in random network gear).

Documentation

Installation

$ npm install snmp-native

Usage

Import

var snmp = require('snmp-native');

new Session(options)

Create a Session. The Session constructor, like most of the other functions, take an options object. The options passed to the Session will be the defaults for any subsequent function calls on that session, but can be overridden as needed. Useful parameters here are host, port and family.

// Create a Session with default settings.
var session = new snmp.Session();

// Create a Session with explicit default host, port, and community.
var session = new snmp.Session({ host: 'device.example.com', port: 161, community: 'special' });

// Create an IPv6 Session.
var session = new snmp.Session({ host: '2001:db8::42', family: 'udp6', community: 'private' });

The following options are recognized as properties in the options object. All can be specified in the Session constructor and optionally overridden at a later time by setting them in the option object to a method call.

For optimum performance when polling many hosts, create a session without specifying the host. Reuse this session for all hosts and specify the host on each get, getAll, etc.

VarBind objects

All of the get* functions return arrays of VarBind as the result to the callback. The VarBind objects have the following properties:

get(options, callback)

Perform a simple GetRequest. Options (in addition to the ones defined above for Session):

Will call the specified callback with an error object (null on success) and the varbind that was received.

session.get({ oid: [1, 3, 6, 1, 4, 1, 42, 1, 0] }, function (error, varbinds) {
    if (error) {
        console.log('Fail :(');
    } else {
        console.log(varbinds[0].oid + ' = ' + varbinds[0].value + ' (' + varbinds[0].type + ')');
    }
});

You can also specify host, community, etc explicitly.

session.get({ oid: [1, 3, 6, 1, 4, 1, 42, 1, 0], host: 'localhost', community: 'test' }, ...);

getNext(options, callback)

Perform a simple GetNextRequest. Options:

Will call the specified callback with an error object (null on success) and the varbind that was received.

session.getNext({ oid: [1, 3, 6, 1, 4, 1, 42, 1, 0] }, function (error, varbinds) {
    if (error) {
        console.log('Fail :(');
    } else {
        console.log(varbinds[0].oid + ' = ' + varbinds[0].value + ' (' + varbinds[0].type + ')');
    }
});

getAll(options, callback)

Perform repeated GetRequests to fetch all the required values. Multiple OIDs will get packed into as few GetRequest packets as possible to minimize roundtrip delays. Gets will be issued serially (not in parallell) to avoid flooding hosts. Options:

The callback will be called with an error object or a list of varbinds. If the options property abortOnError is false (default) any variables that couldn't be fetched will simply be omitted from the results. If it is true, the callback will be called with an error object on any failure. If the combinedTimeout is triggered, the callback is called with an error and the partial results.

var oids = [ [1, 3, 6, 1, 4, 1, 42, 1, 0], [1, 3, 6, 1, 4, 1, 42, 2, 0], ... ];
session.getAll({ oids: oids }, function (error, varbinds) {
    varbinds.forEach(function (vb) {
        console.log(vb.oid + ' = ' + vb.value + ' (' + vb.type + ')');
    });
});

getSubtree(options, callback)

Perform repeated GetNextRequests to fetch all values in the specified tree. Options:

Will call the specified callback with an error object (null on success) and the list of varbinds that was fetched. If the combinedTimeout is triggered, the callback is called with an error and the partial results.

session.getSubtree({ oid: [1, 3, 6, 1, 4, 1, 42] }, function (error, varbinds) {
    if (error) {
        console.log('Fail :(');
    } else {
        varbinds.forEach(function (vb) {
            console.log(vb.oid + ' = ' + vb.value + ' (' + vb.type + ')');
        });
    }
});

set(options, callback)

Perform a simple SetRequest. Options:

Example:

session.set({ oid: [1, 3, 6, 1, 4, 1, 42, 1, 0], value: 42, type: 2 }, function (error, varbind) {
    if (error) {
        console.log('Fail :(');
    } else {
        console.log('The set is done.');
    }
});

If you're not really interested in the outcome of the set (and if you are, why aren't you using scripted telnet or ssh instead to begin with?), you can call it without a callback:

session.set({ oid: [1, 3, 6, 1, 4, 1, 42, 1, 0], value: 42, type: 2 });

close()

Cancels all outstanding requests and frees used OS resources. Outstanding requests will call their callback with the "Cancelled" error set.

Example:

session.close();

License

MIT