SNMPMOD(3)

okay bestie, welcome to SNMPMOD(3) from the Library Functions Manual — this is the bsnmpd loadable module interface and it's genuinely giving main character energy. ✨

🌸 NAME 🌸

okay so this page is the whole group chat for:

INSERT_OBJECT_OID_LINK_INDEX, INSERT_OBJECT_INT_LINK_INDEX,
FIND_OBJECT_OID_LINK_INDEX, NEXT_OBJECT_OID_LINK_INDEX,
FIND_OBJECT_INT_LINK_INDEX, NEXT_OBJECT_INT_LINK_INDEX,
INSERT_OBJECT_OID_LINK, INSERT_OBJECT_INT_LINK, FIND_OBJECT_OID_LINK,
NEXT_OBJECT_OID_LINK, FIND_OBJECT_INT_LINK, NEXT_OBJECT_INT_LINK,
INSERT_OBJECT_OID, INSERT_OBJECT_INT, FIND_OBJECT_OID, FIND_OBJECT_INT,
NEXT_OBJECT_OID, NEXT_OBJECT_INT, this_tick, start_tick, get_ticks,
systemg, comm_define, community, oid_zeroDotZero,
oid_usmUnknownEngineIDs, oid_usmNotInTimeWindows, reqid_allocate,
reqid_next, reqid_base, reqid_istype, reqid_type, timer_start,
timer_start_repeat, timer_stop, fd_select, fd_deselect, fd_suspend,
fd_resume, or_register, or_unregister, buf_alloc, buf_size,
snmp_input_start, snmp_input_finish, snmp_output, snmp_send_port,
snmp_send_trap, snmp_pdu_auth_access string_save, string_commit,
string_rollback, string_get, string_get_max, string_free, ip_save,
ip_rollback, ip_commit, ip_get, oid_save, oid_rollback, oid_commit,
oid_get, index_decode, index_compare, index_compare_off, index_append,
index_append_off, snmpd_usmstats, bsnmpd_get_usm_stats,
bsnmpd_reset_usm_stats, usm_first_user, usm_next_user, usm_find_user,
usm_new_user, usm_delete_user, usm_flush_users, usm_user,
snmpd_target_stat, bsnmpd_get_target_stats, target_first_address,
target_next_address, target_new_address, target_activate_address,
target_delete_address, target_first_param, target_next_param,
target_new_param, target_delete_param, target_first_notify,
target_next_notify, target_new_notify, target_delete_notify,
target_flush_all, target_address, target_param, target_notify

— SNMP daemon loadable module interface. that's the vibe. 💅

📚 LIBRARY 📚

Begemot SNMP library (libbsnmp, -lbsnmp) — that's the one, bestie.

🛠️ SYNOPSIS 🛠️

#include <bsnmp/snmpmod.h>

INSERT_OBJECT_OID_LINK_INDEX(PTR, LIST, LINK, INDEX);

INSERT_OBJECT_INT_LINK_INDEX(PTR, LIST, LINK, INDEX);

FIND_OBJECT_OID_LINK_INDEX(LIST, OID, SUB, LINK, INDEX);

FIND_OBJECT_INT_LINK_INDEX(LIST, OID, SUB, LINK, INDEX);

NEXT_OBJECT_OID_LINK_INDEX(LIST, OID, SUB, LINK, INDEX);

NEXT_OBJECT_INT_LINK_INDEX(LIST, OID, SUB, LINK, INDEX);

INSERT_OBJECT_OID_LINK(PTR, LIST, LINK);

INSERT_OBJECT_INT_LINK(PTR, LIST, LINK);

FIND_OBJECT_OID_LINK(LIST, OID, SUB, LINK);

FIND_OBJECT_INT_LINK(LIST, OID, SUB, LINK);

NEXT_OBJECT_OID_LINK(LIST, OID, SUB, LINK);

NEXT_OBJECT_INT_LINK(LIST, OID, SUB, LINK);

INSERT_OBJECT_OID(PTR, LIST);

INSERT_OBJECT_INT(PTR, LIST);

FIND_OBJECT_OID(LIST, OID, SUB);

FIND_OBJECT_INT(LIST, OID, SUB);

NEXT_OBJECT_OID(LIST, OID, SUB);

NEXT_OBJECT_INT(LIST, OID, SUB);

extern uint64_t this_tick;
extern uint64_t start_tick;

uint64_t
get_ticks(void);

extern struct systemg systemg;

u_int
comm_define(u_int priv, const char *descr, struct lmodule *mod,
    const char *str);

const char *
comm_string(u_int comm);

extern u_int community;
extern const struct asn_oid oid_zeroDotZero;

u_int
reqid_allocate(int size, struct lmodule *mod);

int32_t
reqid_next(u_int type);

int32_t
reqid_base(u_int type);

int
reqid_istype(int32_t reqid, u_int type);

u_int
reqid_type(int32_t reqid);

void *
timer_start(u_int ticks, void (*func)(void *), void *uarg,
    struct lmodule *mod);

void *
timer_start_repeat(u_int ticks, u_int repeat_ticks,
    void (*func)(void *), void *uarg, struct lmodule *mod);

void
timer_stop(void *timer_id);

void *
fd_select(int fd, void (*func)(int, void *), void *uarg,
    struct lmodule *mod);

void
fd_deselect(void *fd_id);

void
fd_suspend(void *fd_id);

int
fd_resume(void *fd_id);

u_int
or_register(const struct asn_oid *oid, const char *descr,
    struct lmodule *mod);

void
or_unregister(u_int or_id);

void *
buf_alloc(int tx);

size_t
buf_size(int tx);

enum snmpd_input_err
snmp_input_start(const u_char *buf, size_t len, const char *source,
    struct snmp_pdu *pdu, int32_t *ip, size_t *pdulen);

enum snmpd_input_err
snmp_input_finish(struct snmp_pdu *pdu, const u_char *rcvbuf,
    size_t rcvlen, u_char *sndbuf, size_t *sndlen, const char *source,
    enum snmpd_input_err ierr, int32_t ip, void *data);

void
snmp_output(struct snmp_pdu *pdu, u_char *sndbuf, size_t *sndlen,
    const char *dest);

void
snmp_send_port(void *trans, const struct asn_oid *port,
    struct snmp_pdu *pdu, const struct sockaddr *addr,
    socklen_t addrlen);

void
snmp_send_trap(const struct asn_oid *oid, ...);

enum snmp_code
snmp_pdu_auth_access(struct snmp_pdu *pdu, int32_t *ip);

int
string_save(struct snmp_value *val, struct snmp_context *ctx,
    ssize_t req_size, u_char **strp);

void
string_commit(struct snmp_context *ctx);

void
string_rollback(struct snmp_context *ctx, u_char **strp);

int
string_get(struct snmp_value *val, const u_char *str, ssize_t len);

int
string_get_max(struct snmp_value *val, const u_char *str, ssize_t len,
    size_t maxlen);

void
string_free(struct snmp_context *ctx);

int
ip_save(struct snmp_value *val, struct snmp_context *ctx, u_char *ipa);

void
ip_rollback(struct snmp_context *ctx, u_char *ipa);

void
ip_commit(struct snmp_context *ctx);

int
ip_get(struct snmp_value *val, u_char *ipa);

int
oid_save(struct snmp_value *val, struct snmp_context *ctx,
    struct asn_oid *oid);

void
oid_rollback(struct snmp_context *ctx, struct asn_oid *oid);

void
oid_commit(struct snmp_context *ctx);

int
oid_get(struct snmp_value *val, const struct asn_oid *oid);

int
index_decode(const struct asn_oid *oid, u_int sub, u_int code, ...);

int
index_compare(const struct asn_oid *oid1, u_int sub,
    const struct asn_oid *oid2);

int
index_compare_off(const struct asn_oid *oid1, u_int sub,
    const struct asn_oid *oid2, u_int off);

void
index_append(struct asn_oid *dst, u_int sub, const struct asn_oid *src);

void
index_append_off(struct asn_oid *dst, u_int sub,
    const struct asn_oid *src, u_int off);

extern struct snmpd_usmstat snmpd_usmstats;

struct snmpd_usmstat *
bsnmpd_get_usm_stats(void);

void
bsnmpd_reset_usm_stats(void);

struct usm_user *
usm_first_user(void);

struct usm_user *
usm_next_user(struct usm_user *uuser);

struct usm_user *
usm_find_user(uint8_t *engine, uint32_t elen, char *uname);

struct usm_user *
usm_new_user(uint8_t *engine, uint32_t elen, char *uname);

void
usm_delete_user(struct usm_user *);

void
usm_flush_users(void);

extern struct usm_user *usm_user;

struct snmpd_target_stats *
bsnmpd_get_target_stats(void);

struct target_address *
target_first_address(void);

struct target_address *
target_next_address(struct target_address *);

struct target_address *
target_new_address(char *);

int
target_activate_address(struct target_address *);

int
target_delete_address(struct target_address *);

struct target_param *
target_first_param(void);

struct target_param *
target_next_param(struct target_param *);

struct target_param *
target_new_param(char *);

int
target_delete_param(struct target_param *);

struct target_notify *
target_first_notify(void);

struct target_notify *
target_next_notify(struct target_notify *);

struct target_notify *
target_new_notify(char *);

int
target_delete_notify(struct target_notify *);

void
target_flush_all(void);

extern const struct asn_oid oid_usmUnknownEngineIDs;
extern const struct asn_oid oid_usmNotInTimeWindows;

💖 DESCRIPTION 💖

okay so here's the vibe: the bsnmpd(1) SNMP daemon ships with a minimal MIB. like, it is not trying to be every MIB at once. that minimal MIB is made of the system group, part of the SNMP MIB, a private configuration MIB, a trap destination table, a UDP port table, a community table, a module table, a statistics group, and a debugging group. every other MIB comes through loadable modules. this setup lets bsnmpd(1) be used for tasks that are not the classical SNMP tasks — main character energy, honestly. 🌈

🧚 MODULE LOADING AND UNLOADING 🧚

modules get loaded by writing to the module table. that table is indexed by a string that identifies the module to the daemon. this identifier is used to select the correct configuration section from the configuration files and to identify resources allocated to this module. a row in the module table is created by writing a string of non-zero length to the begemotSnmpdModulePath column. that string must be the complete path to the file containing the module. to unload a module, write a zero-length string to the path column of an existing row. clean. 💅

modules may depend on each other, so they must be loaded in the correct order. the dependencies are listed in the corresponding manual pages. no cap.

upon loading a module, the SNMP daemon expects the module file to export a global symbol config. this symbol should be a variable of type struct snmp_module:

typedef enum snmpd_proxy_err (*proxy_err_f)(struct snmp_pdu *, void *,
    const struct asn_oid *, const struct sockaddr *, socklen_t,
    enum snmpd_input_err, int32_t);

struct snmp_module {
        const char *comment;
        int (*init)(struct lmodule *, int argc, char *argv[]);
        int (*fini)(void);
        void (*idle)(void);
        void (*dump)(void);
        void (*config)(void);
        void (*start)(void);
        proxy_err_f proxy;
        const struct snmp_node *tree;
        u_int tree_size;
        void (*loading)(const struct lmodule *, int);
};

this structure must be statically initialized, and its fields have the following functions:

• comment — this is a string that will be visible in the module table. it should give some hint about the function of this module. ✨
• init — this function is called upon loading the module. the module pointer should be stored by the module because it is needed in other calls, and the argument vector will contain the arguments to this module from the daemon's command line. this function should return 0 if everything is ok or a UNIX error code (see errno(3)). once the function returns 0, the fini function is called when the module is unloaded. 🫶
• fini — this one fires when the module is getting unloaded 🫶 it's your lil moment to free resources that nothing else is gonna free for you. And bestie, free all the memory, no cap — daemons tend to run very long, so a leak just sits there marinating forever 😭 This function pointer may be NULL if you don't need it.
• idle — if this pointer isn't NULL, the function it points to gets called every time the daemon is about to wait for an event. Lowkey… try to avoid using this feature 🙈 (it's giving "please don't").
• dump — whenever the daemon catches a SIGUSR1 it dumps its internal state via syslog(3) ✨ If the dump field isn't NULL, the daemon calls it to dump the state of the module.
• config — whenever the daemon catches a SIGHUP it re-reads its configuration file. If the config field isn't NULL, it gets called after the config file is read, so your module can adapt to the new config 🎀
• start — if not NULL, this gets called after the module is successfully loaded and initialized, to kick off its actual operation. main character energy 👑
• proxy — if the daemon receives a PDU and that PDU's community string belongs to a community that this module registered, and proxy isn't NULL, then this function is called to handle the PDU 💅
• tree — a pointer to the node array for the MIB tree your module implements 🌳
• tree_size — the number of nodes in tree.
• loading — if this pointer isn't NULL, it's called whenever another module was loaded or unloaded. It gets a pointer to that module plus a flag that's 0 for unloading and 1 for loading 👀

When everything is ok, the daemon merges the module's MIB tree into its current global tree, then calls the module's init() function. If that function returns an error, the module's MIB tree gets removed from the global one and the module is unloaded 💀 If initialization succeeds, the module's start() function is called, and after it returns, the loaded() functions of all modules (including the one that just loaded) are called. periodt.

When the module is unloaded, its MIB tree is removed from the global one, the communities, request id ranges, running timers and selected file descriptors are released, fini() is called, the module file is unloaded, and the loaded() functions of all the other modules are called 🌈

---

✨ IMPLEMENTING TABLES ✨

There's a whole set of macros designed to help you implement SNMP tables, and honestly they ate 🍓

So the tricky part of implementing a table is supporting the GETNEXT operator — GETNEXT has to figure out, given an arbitrary OID, the least table row whose OID is higher than the given OID. The easiest way to do this is to keep the table as an ordered list of structures, each one containing an OID that's the index of the table row. That gives you easy removal, insertion and search. iconic.

These helper macros assume the table is organized as a TAILQ (see queue(3)) and that each structure contains a struct asn_oid used as index 🦋 For simple tables with only an integer or unsigned index, there's an alternate form of the macros that presumes the existence of an integer or unsigned field as the index field.

The macros have names of the form:

{INSERT,FIND,NEXT}_OBJECT_{OID,INT}[_LINK[_INDEX]]

Here's the vibe breakdown:

• The INSERT_*() macros are used in the SET operation to insert a new table row into the table 💖
• The FIND_*() macros are used in the GET operation to find a specific row in the table 🔍
• The NEXT_*() macros are used in the GETNEXT operation to find the next row in the table ⏭️

The last two macros return a pointer to the row structure if a row is found, and NULL otherwise. The *_OBJECT_OID_*() macros assume there's a struct asn_oid being used as the index; the *_OBJECT_INT_*() macros assume there's an unsigned integer field being used as the index 🎀

The *_INDEX() macros let you explicitly name the index field in the parameter INDEX, whereas the other macros just assume that field is named index. The *_LINK_*() macros let you explicitly name the link field of the tail queues — the others assume the link field is named link. Naming the link field explicitly might be necessary when the same structures are held in two or more different tables 👯‍♀️

The arguments to the macros go like this:

• PTR — a pointer to the new structure being inserted into the table.
• LIST — a pointer to the tail queue head.
• LINK — the name of the link field in the row structure.
• INDEX — the name of the index field in the row structure.
• OID — must point to the var field of the value argument to the node operation callback. This is the OID you're searching for 🔎
• SUB — the index of the start of the table index in the OID pointed to by OID. This is usually the same as the sub argument to the node operation callback.

---

🌸 DAEMON TIMESTAMPS 🌸

The variable this_tick holds the tick (and yeah, there are 100 SNMP ticks in a second ⏱️) for when the current PDU processing started.

The variable start_tick holds the tick for when the daemon was started.

The function get_ticks() returns the current tick ✨ So the number of ticks since the daemon started is:

get_ticks() - start_tick

math slay 💅

---

👑 THE SYSTEM GROUP 👑

The scalar fields of the system group live in the global variable systemg:

struct systemg {
    u_char        *descr;
    struct asn_oid    object_id;
    u_char        *contact;
    u_char        *name;
    u_char        *location;
    uint32_t    services;
    uint32_t    or_last_change;
};

---

💬 COMMUNITIES 💬

The SNMP daemon implements a community table 🫶 When a request message comes in, the community string in that message gets compared against each of the community strings in that table. If there's a match, the global variable community is set to the community identifier for that community. Community identifiers are unsigned integers.

For the three standard communities there are three constants defined:

#define COMM_INITIALIZE 0
#define COMM_READ       1
#define COMM_WRITE      2

community is set to COMM_INITIALIZE while the assignments in the configuration file are being processed 💖 And it's set to COMM_READ or COMM_WRITE when the community strings for the read-write or read-only community are found in the incoming PDU.

Modules can define additional communities too 👀 This might be necessary to provide transport proxying (where a PDU received on one communication link gets proxied to another link) or to implement non-UDP access points to SNMP.

A new community is defined with the function comm_define(), which takes these parameters:

• priv — an integer identifying the community to the module. Each module has its own namespace with regard to this parameter, and the community table is indexed with the module name plus this identifier.
• descr — a string with a human readable description of the community. It's visible in the community table 🎀
• mod — the module defining the community.
• str — the initial community string.

The function returns a globally unique community identifier ✨ If an SNMPv1 or SNMPv2 PDU is received whose community string matches, this identifier is set into the global community.

The function comm_string() returns the current community string for the given community.

All communities defined by a module are automatically released when the module is unloaded 🦋

---

🔐 THE USER-BASED SECURITY GROUP 🔐

The scalar statistics of the USM group live in the global variable snmpd_usmstats:

struct snmpd_usmstat {
    uint32_t    unsupported_seclevels;
    uint32_t    not_in_time_windows;
    uint32_t    unknown_users;
    uint32_t    unknown_engine_ids;
    uint32_t    wrong_digests;
    uint32_t    decrypt_errors;
};

bsnmpd_get_usm_stats() returns a pointer to the global structure containing the statistics 📊 And bsnmpd_reset_usm_stats() clears the statistics of the USM group, fresh start energy ✨

The daemon also maintains a global list of configured USM users:

struct usm_user {
    struct snmp_user        suser;
    uint8_t                user_engine_id[SNMP_ENGINE_ID_SIZ];
    uint32_t            user_engine_len;
    char                user_public[SNMP_ADM_STR32_SIZ];
    uint32_t            user_public_len;
    int32_t                status;
    int32_t                type;
    SLIST_ENTRY(usm_user)        up;
};

This structure represents a USM user 💜 The daemon only responds to SNMPv3 PDUs whose user credentials match a USM user entry in its global list. If an SNMPv3 PDU comes in whose security model is USM, the global usm_user is set to point at the user entry matching the credentials in the PDU.

But here's the thing — the daemon does not create or remove USM users 😤 it just gives an interface to external loadable module(s) to manage the list:

• usm_new_user() adds a user entry to the list
• usm_delete_user() deletes an existing entry from the list
• usm_flush_users() removes all configured USM users
• usm_first_user() returns the first user in the list, or NULL if the list is empty
• usm_next_user() returns the next user after a given entry, if one exists, or NULL
• usm_find_user() returns the USM user entry matching the given engine and uname, or NULL if no user with that name and engine id is in the list

The list is sorted according to the USM user name and Engine ID 🔤 iykyk.

---

🎯 THE MANAGEMENT TARGET GROUP 🎯

The Management Target group holds target address information used when sending SNMPv3 notifications 📨

The scalar statistics of the Management Target group live in the global variable snmpd_target_stats:

struct snmpd_target_stats {
    uint32_t            unavail_contexts;
    uint32_t            unknown_contexts;
};

bsnmpd_get_target_stats() returns a pointer to the global structure containing the statistics ⭐

Three global lists of configured management target addresses, parameters and notifications respectively are maintained by the daemon 👑

struct target_address {
        char                            name[SNMP_ADM_STR32_SIZ];
        uint8_t                         address[SNMP_UDP_ADDR_SIZ];
        int32_t                         timeout;
        int32_t                         retry;
        char                            taglist[SNMP_TAG_SIZ];
        char                            paramname[SNMP_ADM_STR32_SIZ];
        int32_t                         type;
        int32_t                         socket;
        int32_t                         status;
        SLIST_ENTRY(target_address)     ta;
};

Okay so this one is the SNMPv3 Management Target address glow-up 💅 — every single time a SNMP TRAP gets sent, the daemon literally sprays it out to all the active Management Target addresses chilling in its global list. Like a group chat blast, no cap 📢

struct target_param {
        char                            name[SNMP_ADM_STR32_SIZ];
        int32_t                         mpmodel;
        int32_t                         sec_model;
        char                            secname[SNMP_ADM_STR32_SIZ];
        enum snmp_usm_level             sec_level;
        int32_t                         type;
        int32_t                         status;
        SLIST_ENTRY(target_param)       tp;
};

This struct is the whole vibe check for how we talk to the addresses above — it's the info used to generate SNMP messages for the associated SNMPv3 Management Target addresses 🫶

struct target_notify {
        char                            name[SNMP_ADM_STR32_SIZ];
        char                            taglist[SNMP_TAG_SIZ];
        int32_t                         notify_type;
        int32_t                         type;
        int32_t                         status;
        SLIST_ENTRY(target_notify)      tn;
};

And this cutie represents Notification Tag entries ✨ — SNMP notifications get sent to a Target address for every entry in the Management Target Address list whose tag matches the tag in this struct. Tag matching is so it's giving curated guest list 🎀

---

So here's the tea: the daemon does not create or remove entries in the Management Target group lists itself. It just hands an interface to external loadable module(s) and lets them manage the lists. Delegation, main character energy 👑

• target_new_address() — adds a target address entry.
• target_delete_address() — deletes an existing entry from the target address list.
• target_activate_address() — creates a socket associated with the target address entry so SNMP notifications may actually be sent to that target address. (before this, it's giving "all dressed up with nowhere to go" 😭)
• target_first_address() — returns a pointer to the first target address entry in the list.
• target_next_address() — returns a pointer to the next target address of a given entry, if one exists.
• target_new_param() — adds a target parameters' entry.
• target_delete_param() — deletes an existing entry from the target parameters list.
• target_first_param() — returns a pointer to the first target parameters' entry in the list.
• target_next_param() — returns a pointer to the next target parameters of a given entry, if one exists.
• target_new_notify() — adds a notification target entry.
• target_delete_notify() — deletes an existing entry from the notification target list.
• target_first_notify() — returns a pointer to the first notification target entry in the list.
• target_next_notify() — returns a pointer to the next notification target of a given entry, if one exists.
• target_flush_all() — removes all configured data from the three global Management Target Group lists. Nuclear option, lowkey 💀

🌈 WELL KNOWN OIDS 🌈

The global variable oid_zeroDotZero holds the OID 0.0. Iconic, minimal, does exactly what it says on the tin.

The global variables oid_usmUnknownEngineIDs and oid_usmNotInTimeWindows hold the OIDs 1.3.6.1.6.3.15.1.1.4.0 and 1.3.6.1.6.3.15.1.1.2.0, which get used in SNMPv3 USM Engine Discovery. Yeah, those numbers, you gotta copy them exactly, no paraphrasing bestie 🦋

📨 REQUEST ID RANGES 📨

So if a module implements SNMP client functions alongside SNMP agent functions, it might need to tell SNMP requests apart by their identifier — that way responses get routed to the right sub-system without chaos. Request id ranges are the whole solution: they let you grab globally non-overlapping sub-ranges out of the entire 31-bit id range. Chef's kiss allocation strategy 🤌

You allocate a request id range with reqid_allocate(). The arguments are the size of the range and the module allocating the range. Like, for example:

id = reqid_allocate(1000, module);

That allocates a range of 1000 request ids. The function returns the request id range identifier, or 0 if there's just not enough identifier space (sad but honest 😔). And reqid_base() returns the lowest request id in the given range.

Request ids get allocated starting at the lowest one and go linear throughout the range. Pro tip fr fr: if the client app might have a whole lot of outstanding requests, the range has to be big enough that an id doesn't get reused until it's really expired. reqid_next() returns the sequentially next id in the range.

• reqid_istype() — checks whether the request id reqid is inside the range identified by type.
• reqid_type() — returns the range identifier for the given reqid, or 0 if that request id isn't in any of the ranges.

⏰ TIMERS ⏰

The SNMP daemon supports an arbitrary number of timers with SNMP tick granularity. Fancy.

timer_start() arranges for the callback func to be called with the argument uarg after ticks SNMP ticks have expired. mod is the module that starts the timer. Heads up: these timers are one-shot — they do not restart, periodt 💅

Repeatable timers are started with timer_start_repeat(), which takes an additional argument repeat_ticks. Here's the breakdown:

• ticks — number of ticks until the first execution of the callback.
• repeat_ticks — number of ticks between invocations of the callback.

Ngl, note that currently the number of initial ticks may silently be set identical to the number of ticks between callback invocations. Not us pretending that's fine 🙈

The function returns a timer identifier you can use to stop the timer via timer_stop(). And if a module gets unloaded, all timers started by that module that haven't expired yet are stopped. Cleanup crew, we love to see it 🧚

🔌 FILE DESCRIPTOR SUPPORT 🔌

Sometimes a module needs to get input from socket file descriptors without blocking the daemon (like, say, to implement alternative SNMP transports). Very demure, very mindful.

fd_select() causes the callback function func to be called with the file descriptor fd and the user argument uarg whenever fd can be read or has a close condition. If the file descriptor isn't in non-blocking mode, it gets set to non-blocking mode — surprise, you're non-blocking now ✨

If the callback isn't needed anymore, call fd_deselect() with the value returned from fd_select(). And all file descriptors selected by a module are automatically deselected when the module is unloaded. Zero loose ends.

To temporarily suspend the file descriptor registration, call fd_suspend(). This also switches the file descriptor back to blocking mode if it was blocking before the call to fd_select(). Lowkey this is necessary to do synchronous input on a selected socket. The effect of fd_suspend() can be undone with fd_resume(). Pause and unpause, the duality of woman 🦋

📦 OBJECT RESOURCES 📦

The system group contains an object resource table. A module can create an entry in this table by calling or_register() with:

• the oid to be registered,
• a textual description in str,
• and a pointer to the module mod.

The registration can be removed again with or_unregister(). And all registrations belonging to a module are automatically removed if the module is unloaded. Self-cleaning, we stan 🌸

🛢️ TRANSMIT AND RECEIVE BUFFERS 🛢️

A buffer is allocated via buf_alloc(). The argument must be 1 for transmit buffers and 0 for receive buffers — binary, no in-between, no vibes-based guessing 💀

The function may return NULL if there's no memory available. (Not a mood, just a fact.)

The current buffersize can be obtained with buf_size().

🔥 PROCESSING PDUS 🔥

Okay so bestie, if your module needs to do its own PDU processing (think proxying energy), these functions are literally your backstage pass 💅

• snmp_input_start() — decodes the PDU, searches the community, and sets the global this_tick. It returns one of these error codes:
  • SNMPD_INPUT_OK — everything ok, continue with processing ✨
  • SNMPD_INPUT_FAILED — the PDU could not be decoded, has a wrong version, or has an unknown community string 💀
  • SNMPD_INPUT_VALBADLEN — a SET PDU had a value field in a binding with a wrong length field in an ASN.1 header
  • SNMPD_INPUT_VALRANGE — a SET PDU had a value field in a binding with a value that is out of range for the given ASN.1 type
  • SNMPD_INPUT_VALBADENC — a SET PDU had a value field in a binding with wrong ASN.1 encoding
  • SNMPD_INPUT_TRUNC — the buffer appears to contain a valid begin of a PDU, but is too short. For streaming transports this means that the caller must save what they already have, try to obtain more input, and reissue this input to the function. For datagram transports this means that part of the datagram was lost and the input should be ignored 🫠
• snmp_input_finish() — does the other half of processing: if snmp_input_start() did not return OK, it tries to construct an error response. If the start was OK, it calls the correct function from bsnmpagent(3) to execute the request and, depending on the outcome, constructs a response or error response PDU or ignores the request PDU. It returns either SNMPD_INPUT_OK or SNMPD_INPUT_FAILED. In the first case a response PDU was constructed and should be sent 👑
• snmp_output() — takes a PDU and encodes it.
• snmp_send_port() — takes a PDU, encodes it, and sends it through the given port (identified by the transport and the index in the port table) to the given address.
• snmp_send_trap() — sends a trap to all trap destinations. The arguments are the oid identifying the trap and a NULL-terminated list of struct snmp_value pointers that are to be inserted into the trap binding list.
• snmp_pdu_auth_access() — verifies whether access to the object IDs contained in the pdu should be granted or denied, according to the configured View-Based Access rules. ip contains the index of the first varbinding to which access was denied, or 0 if access to all varbindings in the PDU is granted 🛡️

---

🧸 SIMPLE ACTION SUPPORT 🧸

For simple scalar variables that need no dependencies, a number of support functions is available to handle the set, commit, rollback, and get. No cap, this is the low-effort slay section 💖

The following functions are used for OCTET STRING scalars, either NUL terminated or not:

• string_save() — should be called for SNMP_OP_SET. value and ctx are the resp. arguments to the node callback. valp is a pointer to the pointer that holds the current value, and req_size should be -1 if any size of the string is acceptable or a number larger or equal zero if the string must have a specific size. The function saves the old value in the scratch area (note, that any initial value must have been allocated by malloc(3)), allocates a new string, copies over the new value, NUL-terminates it, and sets the new current value ✨
• string_commit() — simply frees the saved old value in the scratch area.
• string_rollback() — frees the new value, and puts back the old one.
• string_get() — is used for GET or GETNEXT. The function (and yes, the manpage sentence literally stops there, bestie 😭)
• string_get_max() — can be used instead of string_get() to ensure that the returned string has a certain maximum length. If len is -1, the length is computed via strlen(3) from the current string value. If the current value is NULL, a OCTET STRING of zero length is returned.
• string_free() — must be called if either rollback or commit fails to free the saved old value.

The following functions are used to process scalars of type IP-address:

• ip_save() — saves the current value in the scratch area and sets the new value from valp.
• ip_commit() — does nothing.
• ip_rollback() — restores the old IP address from the scratch area.
• ip_get() — retrieves the IP current address.

The following functions handle OID-typed variables:

• oid_save() — saves the current value in the scratch area by allocating a struct asn_oid with malloc(3) and sets the new value from oid.
• oid_commit() — frees the old value in the scratch area.
• oid_rollback() — restores the old OID from the scratch area and frees the old OID.
• oid_get() — retrieves the OID 🌈

---

🧚 TABLE INDEX HANDLING 🧚

The following functions help in handling table indexes:

• index_decode() — decodes the index part of the OID. The parameter oid must be a pointer to the var field of the value argument of the node callback. The sub argument must be the index of the start of the index in the OID (this is the sub argument to the node callback). code is the index expression (parameter idx to the node callback). These parameters are followed by parameters depending on the syntax of the index elements as follows:
  • INTEGER — int32_t * expected as argument.
  • COUNTER64 — uint64_t * expected as argument. Note, that this syntax is illegal for indexes.
  • OCTET STRING — a u_char ** and a size_t * expected as arguments. A buffer is allocated to hold the decoded string.
  • OID — a struct asn_oid * is expected as argument.
  • IP ADDRESS — a u_int8_t * expected as argument that points to a buffer of at least four byte.
  • COUNTER, GAUGE, TIMETICKS — a u_int32_t expected.
  • NULL — no argument expected.
• index_compare() — compares the current variable with an OID. oid1 and sub come from the node callback arguments value->var and sub resp. oid2 is the OID to compare to. The function returns -1, 0, +1 when the variable is lesser, equal, higher to the given OID. oid2 must contain only the index part of the table column.
• index_compare_off() — is equivalent to index_compare() except that it takes an additional parameter off that causes it to ignore the first off components of both indexes.
• index_append() — appends OID src beginning at position sub to dst.
• index_append_off() — appends OID src beginning at position off to dst beginning at position sub + off.

---

👀 SEE ALSO 👀

• gensnmptree(1), bsnmpd(1), bsnmpagent(3), bsnmpclient(3), bsnmplib(3)

🎀 STANDARDS 🎀

This implementation conforms to the applicable IETF RFCs and ITU-T recommendations. Periodt.

👑 AUTHORS 👑

Hartmut Brandt <harti@FreeBSD.org>

---

💖 That's the whole page, bestie — this is the Debian version, dated December 19, 2010, for SNMPMOD(3). No cap, you ate. 🫶