diff options
Diffstat (limited to 'man')
54 files changed, 11548 insertions, 0 deletions
diff --git a/man/Makefile.in b/man/Makefile.in new file mode 100644 index 0000000..5627cc0 --- /dev/null +++ b/man/Makefile.in @@ -0,0 +1,278 @@ +# +# Makefile for the man page directory +# +top_builddir=.. +VPATH = @srcdir@ + +# +# install stuff +# + +OTHERINSTALL=maninstall +OTHERUNINSTALL=manuninstall +# +# local stuff +# + +MAN1 = snmpinform.1 snmp-bridge-mib.1 + +@NETSNMP_HAVE_AGENTX_LIBS_TRUE@AGENTXTRAP = agentxtrap.1 +@NETSNMP_HAVE_AGENTX_LIBS_FALSE@AGENTXTRAP = + +MAN1G = $(AGENTXTRAP) snmpbulkget.1 snmpcmd.1 snmpget.1 snmpset.1 snmpwalk.1 \ + snmpbulkwalk.1 snmpgetnext.1 snmptest.1 snmptranslate.1 snmptrap.1 \ + snmpusm.1 snmpvacm.1 snmptable.1 snmpstatus.1 snmpconf.1 mib2c.1 \ + snmpnetstat.1 snmpdelta.1 snmpdf.1 encode_keychange.1 fixproc.1 \ + net-snmp-config.1 mib2c-update.1 tkmib.1 traptoemail.1 \ + net-snmp-create-v3-user.1 + +# If MAN3 is populated again, then remember to re-enable the corresponding +# action line within the 'maninstall' target +MAN3 = +MAN3_API = netsnmp_mib_api.3 netsnmp_config_api.3 snmp_alarm.3 \ + netsnmp_session_api.3 netsnmp_sess_api.3 netsnmp_trap_api.3 netsnmp_varbind_api.3 netsnmp_pdu_api.3 +MAN3G = default_store.3 netsnmp_agent_api.3 $(MAN3_API) +MAN5G = snmpd.conf.5 snmptrapd.conf.5 snmp.conf.5 snmp_config.5 variables.5 \ + mib2c.conf.5 snmpd.examples.5 snmpd.internal.5 +MAN8G = snmptrapd.8 snmpd.8 + +MIB_ALIASES = add_mibdir.3 add_module_replacement.3 \ + fprint_description.3 fprint_objid.3 get_module_node.3 \ + netsnmp_init_mib.3 netsnmp_read_module.3 \ + print_description.3 print_mib.3 print_objid.3 \ + read_all_mibs.3 read_mib.3 read_objid.3 \ + shutdown_mib.3 snmp_parse_oid.3 snmp_set_mib_errors.3 \ + snmp_set_mib_warnings.3 snmp_set_save_descriptions.3 \ + snprint_description.3 snprint_objid.3 +CONFIG_ALIASES = config_perror.3 config_pwarn.3 \ + read_config_print_usage.3 read_configs.3 read_premib_configs.3 \ + register_app_config_handler.3 register_app_prenetsnmp_mib_handler.3 \ + register_config_handler.3 register_const_config_handler.3 \ + register_mib_handlers.3 register_prenetsnmp_mib_handler.3 \ + unregister_all_config_handlers.3 \ + unregister_app_config_handler.3 unregister_config_handler.3 +ALARM_ALIASES = snmp_alarm_register.3 snmp_alarm_register_hr.3 snmp_alarm_unregister.3 +SESSION_ALIASES = snmp_api_errstring.3 snmp_close.3 snmp_error.3 \ + snmp_open.3 snmp_perror.3 snmp_read.3 snmp_select_info.3 \ + snmp_send.3 snmp_sess_perror.3 snmp_timeout.3 +SSESS_ALIASES = snmp_sess_async_send.3 snmp_sess_close.3 snmp_sess_error.3 \ + snmp_sess_init.3 snmp_sess_open.3 snmp_sess_read.3 \ + snmp_sess_select_info.3 snmp_sess_send.3 \ + snmp_sess_session.3 snmp_sess_timeout.3 +TRAP_ALIASES = send_easy_trap.3 send_trap_vars.3 send_v2trap.3 +VARBIND_ALIASES = fprint_value.3 fprint_variable.3 \ + print_value.3 print_variable.3 \ + snmp_add_null_var.3 snmp_clone_varbind.3 \ + snmp_free_var.3 snmp_free_varbind.3 \ + snmp_pdu_add_variable.3 \ + snmp_set_var_objid.3 snmp_set_var_typed_integer.3 \ + snmp_set_var_typed_value.3 snmp_set_var_value.3 \ + snmp_varlist_add_variable.3 snprint_value.3 snprint_variable.3 +PDU_ALIASES = snmp_clone_pdu.3 snmp_fix_pdu.3 snmp_free_pdu.3 snmp_pdu_create.3 + + + +MANALIASES=$(MIB_ALIASES) $(CONFIG_ALIASES) $(ALARM_ALIASES) $(SESSION_ALIASES) \ + $(SSESS_ALIASES) $(TRAP_ALIASES) $(VARBIND_ALIASES) $(PDU_ALIASES) +MANALL = $(MAN1) $(MAN1G) $(MAN3) $(MAN3G) $(MAN5G) $(MAN8G) $(MANALIASES) + +TARGETS = $(MAN5G) $(MAN1G) $(MAN3G) $(MAN8G) +OTHERCLEANTARGETS=$(TARGETS) default_store.3.h $(MANALIASES) manaliases + +all: $(TARGETS) standardall manaliases + +manaliases: Makefile + touch manaliases + @for i in $(MAN3_API) ; do \ + for j in `sed -n '/^.SH NAME/,/^.SH SYNOPSIS/p' $$i | sed -e 's/.- .*//' | sed 's/,.*//' | @EGREP@ -v '^.SH ' `; do \ + echo "making man page alias $$j -> $$i APIs" ; \ + echo ".so man3/$$i" > $$j.3 ; \ + done \ + done + +agentxtrap.1: $(srcdir)/agentxtrap.1.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/agentxtrap.1.def > agentxtrap.1 + +snmpbulkget.1: $(srcdir)/snmpbulkget.1.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/snmpbulkget.1.def > snmpbulkget.1 + +snmpbulkwalk.1: $(srcdir)/snmpbulkwalk.1.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/snmpbulkwalk.1.def > snmpbulkwalk.1 + +snmpcmd.1: $(srcdir)/snmpcmd.1.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/snmpcmd.1.def > snmpcmd.1 + +snmpconf.1: $(srcdir)/snmpconf.1.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/snmpconf.1.def > snmpconf.1 + +snmpd.8: $(srcdir)/snmpd.8.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/snmpd.8.def > snmpd.8 + +snmpdelta.1: $(srcdir)/snmpdelta.1.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/snmpdelta.1.def > snmpdelta.1 + +snmpdf.1: $(srcdir)/snmpdf.1.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/snmpdf.1.def > snmpdf.1 + +snmpget.1: $(srcdir)/snmpget.1.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/snmpget.1.def > snmpget.1 + +snmpgetnext.1: $(srcdir)/snmpgetnext.1.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/snmpgetnext.1.def > snmpgetnext.1 + +snmpnetstat.1: $(srcdir)/snmpnetstat.1.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/snmpnetstat.1.def > snmpnetstat.1 + +snmpset.1: $(srcdir)/snmpset.1.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/snmpset.1.def > snmpset.1 + +snmpstatus.1: $(srcdir)/snmpstatus.1.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/snmpstatus.1.def > snmpstatus.1 + +snmptable.1: $(srcdir)/snmptable.1.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/snmptable.1.def > snmptable.1 + +snmptest.1: $(srcdir)/snmptest.1.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/snmptest.1.def > snmptest.1 + +snmptranslate.1: $(srcdir)/snmptranslate.1.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/snmptranslate.1.def > snmptranslate.1 + +snmptrap.1: $(srcdir)/snmptrap.1.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/snmptrap.1.def > snmptrap.1 + +snmpusm.1: $(srcdir)/snmpusm.1.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/snmpusm.1.def > snmpusm.1 + +snmpvacm.1: $(srcdir)/snmpvacm.1.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/snmpvacm.1.def > snmpvacm.1 + +mib2c.1: $(srcdir)/mib2c.1.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/mib2c.1.def > mib2c.1 + +mib2c-update.1: $(srcdir)/mib2c-update.1.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/mib2c-update.1.def > mib2c-update.1 + +snmpwalk.1: $(srcdir)/snmpwalk.1.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/snmpwalk.1.def > snmpwalk.1 + +encode_keychange.1: $(srcdir)/encode_keychange.1.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/encode_keychange.1.def > encode_keychange.1 + +fixproc.1: $(srcdir)/fixproc.1.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/fixproc.1.def > fixproc.1 + +net-snmp-config.1: $(srcdir)/net-snmp-config.1.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/net-snmp-config.1.def > net-snmp-config.1 + +net-snmp-create-v3-user.1: $(srcdir)/net-snmp-create-v3-user.1.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/net-snmp-create-v3-user.1.def > net-snmp-create-v3-user.1 + +tkmib.1: $(srcdir)/tkmib.1.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/tkmib.1.def > $@ + +traptoemail.1: $(srcdir)/traptoemail.1.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/traptoemail.1.def > $@ + +netsnmp_varbind_api.3: $(srcdir)/netsnmp_varbind_api.3.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/netsnmp_varbind_api.3.def > $@ + +netsnmp_pdu_api.3: $(srcdir)/netsnmp_pdu_api.3.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/netsnmp_pdu_api.3.def > $@ + +netsnmp_session_api.3: $(srcdir)/netsnmp_session_api.3.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/netsnmp_session_api.3.def > $@ + +netsnmp_mib_api.3: $(srcdir)/netsnmp_mib_api.3.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/netsnmp_mib_api.3.def > $@ + +netsnmp_config_api.3: $(srcdir)/netsnmp_config_api.3.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/netsnmp_config_api.3.def > $@ + +snmp_alarm.3: $(srcdir)/snmp_alarm.3.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/snmp_alarm.3.def > $@ + +netsnmp_sess_api.3: $(srcdir)/netsnmp_sess_api.3.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/netsnmp_sess_api.3.def > $@ + +netsnmp_agent_api.3: $(srcdir)/netsnmp_agent_api.3.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/netsnmp_agent_api.3.def > $@ + +netsnmp_trap_api.3: $(srcdir)/netsnmp_trap_api.3.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/netsnmp_trap_api.3.def > $@ + +snmp.conf.5: $(srcdir)/snmp.conf.5.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/snmp.conf.5.def > $@ + +snmp_config.5: $(srcdir)/snmp_config.5.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/snmp_config.5.def > $@ + +snmpd.conf.5: $(srcdir)/snmpd.conf.5.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/snmpd.conf.5.def > $@ + +snmpd.examples.5: $(srcdir)/snmpd.examples.5.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/snmpd.examples.5.def > $@ + +snmpd.internal.5: $(srcdir)/snmpd.internal.5.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/snmpd.internal.5.def > $@ + +snmptrapd.conf.5: $(srcdir)/snmptrapd.conf.5.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/snmptrapd.conf.5.def > $@ + +variables.5: $(srcdir)/variables.5.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/variables.5.def > $@ + +snmptrapd.8: $(srcdir)/snmptrapd.8.def ../sedscript + $(SED) -f ../sedscript < $(srcdir)/snmptrapd.8.def > $@ + +default_store.3.h: $(srcdir)/../include/net-snmp/library/default_store.h + awk '{ if ($$0 == " * begin storage definitions ") { p = 1 } else if ($$0 == " * end storage definitions ") { p = 0 } else if (p) { print $$0}}' < $(srcdir)/../include/net-snmp/library/default_store.h > default_store.3.h + +default_store.3: $(srcdir)/default_store.3.top default_store.3.h $(srcdir)/default_store.3.bot + $(SED) -f ../sedscript < $(srcdir)/default_store.3.top > default_store.3 + cat default_store.3.h $(srcdir)/default_store.3.bot >> default_store.3 + +mib2c.conf.5: $(top_srcdir)/local/mib2c mib2c.conf.5.in $(srcdir)/mib2c.extract.pl + @if test "x$(PERL)" != "x" ; then \ + $(PERL) $(srcdir)/mib2c.extract.pl $(top_srcdir)/local/mib2c $(srcdir)/mib2c.conf.5.in > mib2c.conf.5; \ + else \ + touch mib2c.conf.5 ; \ + fi + +maninstall: maninstalldirs $(MAN1) $(MAN1G) $(MAN3) $(MAN5G) $(MAN8) $(MANALIASES) + @for i in $(MAN1) ; do $(INSTALL_DATA) $(srcdir)/$$i $(INSTALL_PREFIX)$(man1dir) ; echo "install: installed $$i in $(INSTALL_PREFIX)$(man1dir)" ; done + @$(INSTALL_DATA) $(MAN1G) $(INSTALL_PREFIX)$(man1dir) + @for i in $(MAN1G) ; do echo "install: installed $$i in $(INSTALL_PREFIX)$(man1dir)" ; done + #EMPTY LIST#@for i in $(MAN3) ; do $(INSTALL_DATA) $(srcdir)/$$i $(INSTALL_PREFIX)$(man3dir) ; echo "install: installed $$i in $(INSTALL_PREFIX)$(man3dir)" ; done + @$(INSTALL_DATA) $(MAN3G) $(INSTALL_PREFIX)$(man3dir) + @for i in $(MAN3G) ; do echo "install: installed $$i in $(INSTALL_PREFIX)$(man3dir)" ; done + @$(INSTALL_DATA) $(MANALIASES) $(INSTALL_PREFIX)$(man3dir) + @for i in $(MANALIASES) ; do echo "install: installed $$i in $(INSTALL_PREFIX)$(man3dir)" ; done + -@$(INSTALL_DATA) $(MAN5G) $(INSTALL_PREFIX)$(man5dir) + @for i in $(MAN5G) ; do echo "install: installed $$i in $(INSTALL_PREFIX)$(man5dir)" ; done + @$(INSTALL_DATA) $(MAN8G) $(INSTALL_PREFIX)$(man8dir) + @for i in $(MAN8G) ; do echo "install: installed $$i in $(INSTALL_PREFIX)$(man8dir)" ; done + +manuninstall: + @for i in $(MAN1G) $(MAN1) ; do rm -f $(INSTALL_PREFIX)$(man1dir)/$$i ; echo "removed $$i from $(INSTALL_PREFIX)$(man1dir)" ; done + @for i in $(MAN3G) $(MAN3) $(MANALIASES); do rm -f $(INSTALL_PREFIX)$(man3dir)/$$i ; echo "removed $$i from $(INSTALL_PREFIX)$(man3dir)" ; done + @for i in $(MAN5G) ; do rm -f $(INSTALL_PREFIX)$(man5dir)/$$i ; echo "removed $$i from $(INSTALL_PREFIX)$(man5dir)" ; done + @for i in $(MAN8G) ; do rm -f $(INSTALL_PREFIX)$(man8dir)/$$i ; echo "removed $$i from $(INSTALL_PREFIX)$(man8dir)" ; done + +maninstalldirs: + @$(SHELL) $(srcdir)/../mkinstalldirs $(INSTALL_PREFIX)$(man1dir) $(INSTALL_PREFIX)$(man3dir) $(INSTALL_PREFIX)$(man5dir) $(INSTALL_PREFIX)$(man8dir) + + +# +# internal administrative +# +html: $(MANALL) + for i in $(MANALL); do \ +# if test `wc -l $$i | awk '{print $$1}'` != 1 ; then \ + base=`echo $$i | sed 's/.[0-9]$$//;'` ; \ + echo "<HTML><BODY bgcolor=\"#ffffff\" background=\"../ucd-snmp-bg3.gif\"><PRE>" > $$base.html; \ + man2html -r ./$$i | $(PERL) -p -e 's/HREF=\"..\/man.\//HREF=\"/g;s/\.[1-9]\.html/.html/g;' | grep -v 'Content-type:' >> $$base.html; \ + a="$$a $$i"; \ +# fi ; \ + done ;\ + $(PERL) make_index.pl man_sections.txt $$a > index.html diff --git a/man/agentxtrap.1.def b/man/agentxtrap.1.def new file mode 100644 index 0000000..331325f --- /dev/null +++ b/man/agentxtrap.1.def @@ -0,0 +1,110 @@ +.TH AGENTXTRAP 1 "20 Dec 2009" VVERSIONINFO "Net-SNMP" +.SH NAME +agentxtrap - send an AgentX NotifyPDU to an AgentX master agent +.SH SYNOPSIS +.B agentxtrap +.RI [ OPTIONS ] " trap-oid " [ "OID TYPE VALUE" ...] +.SH DESCRIPTION +.B agentxtrap +issues an AgentX NotifyPDU to a master agent. One or more object +identifiers (OIDs) can be given as arguments on the command line. +A type and a value must accompany each object identifier. +Each variable name is given in the format specified in +.IR variables(5) . +.PP +.SH OPTIONS +.PD 0 +.TP 6 +.BI \-c "\| contextName\^" +if the +.B \-c +option is present then the notification is sent in the nondefault name context. +.TP +.BI \-U "\| uptime\^" +if the +.B \-U +option is present then that value, parsed as centiseconds, is taken to be the +sysUpTime field of the application. +.TP +.BI \-x "\| ADDRESS\^" +if the +.B \-x +option is present then contact the AgentX master at ADDRESS and not the default +one. +.PD +.PP +Additionally all the options described in +.IR snmpcmd(1) +under the +.BR "MIB PARSING OPTIONS" ", " "LOGGING OPTIONS" " and " "INPUT OPTIONS" +headers as well as the +.BR -d ", " -D ", " -m " and " -M +options are supported. +.PP +In +.I OID TYPE VALUE +the parsing of the +.I VALUE +field is controlled by the +.I TYPE +field. The possible values for the +.I TYPE +field is one of the following characters: +.RS +.PD 0 +.TP 3 +.B = +Let +.I OID +decide how +.I VALUE +should be interpreted +.TP +.B i +INTEGER +.TP +.B u +Unsigned +.TP +.B c +Counter32 +.TP +.B s +OCTET STRING of chaacters +.TP +.B x +OCTET STRING, entered as a sequence of optionally space separated hexadecimal +digit pairs +.TP +.B d +OCTET STRING, entered as a sequence of space separated decimal digits in the +range 0 - 255 +.TP +.B n +NULL +.TP +.B o +OBJECT IDENTIFIER +.TP +.B t +TimeTicks +.TP +.B a +IpAddress +.TP +.B b +BITS +.PD +.RE +which are handled in the same way as the +.B snmpset +command. +.PP +.SH EXAMPLES +To send a generic linkUp trap to the manager for interface 1 the following +command can be used: +.PP +agentxtrap netSnmp.0.3 ifindex.1 i 1 +.PP +.SH SEE ALSO +snmpcmd(1), snmpset(1), variables(5), RFC 2741 diff --git a/man/default_store.3.bot b/man/default_store.3.bot new file mode 100644 index 0000000..ebd2bf6 --- /dev/null +++ b/man/default_store.3.bot @@ -0,0 +1,120 @@ +.fi +.SH FUNCTIONS +.TP +.BI "int netsnmp_ds_set_boolean(int " store ", int " which ", int " val ");" +Stores +.I TRUE +if +.I val +!= 0 or else +.I FALSE +into the bool_storage[store][which] slot. Returns +.B SNMPERR_GENERR +if the +.IR store " and " which +parameters do not correspond to a valid slot, or +.B SNMPERR_SUCCESS +otherwise. +.TP +.BI "int netsnmp_ds_get_boolean(int " store ", int " which ");" +Returns 1 if bool_storage[store][which] is +.IR TRUE +or 0 if not. May also return +.B SNMPERR_GENERR +if the +.IR store " and " which +parameters do not correspond to a valid slot. +.TP +.BI "int netsnmp_ds_set_string(int " store ", int " which ", const char *" val ");" +Stores +.I val +into the string_storage[store][which] slot. Returns +.B SNMPERR_SUCCESS +normally, or +.B SNMPERR_GENERR +if the +.IR store " and " which +parameters do not correspond to a valid slot. +.TP +.BI "char *netsnmp_ds_get_string(int " store ", int " which ");" +Returns the string which has been stored in the +string_storage[store][which] slot, or +.B NULL +if the +.IR store " and " which +parameters do not correspond to a valid slot. +.TP +.BI "netsnmp_ds_set_int(int " store ", int " which ", int " val ");" +Stores +.I val +into the int_storage[store][which] slot. Returns +.B SNMPERR_GENERR +if the +.IR store " and " which +parameters do not correspond to a valid slot, or +.B SNMPERR_SUCCESS +otherwise. +.TP +.BI "int netsnmp_ds_get_int(int " store ", int " which ");" +Returns the integer which has been stored in the +int_storage[store][which] slot, or +.B SNMPERR_GENERR +if the +.IR store " and " which +parameters do not correspond to a valid slot. +.TP +.BI "void netsnmp_ds_shutdown(void);" +Reclaims memory used to hold information gathered by +.BR netsnmp_ds_register_config " and " netsnmp_ds_register_premib . +.TP +.BI "int netsnmp_ds_register_config(u_char " type ", const char *" ftype ", const char *" token ", int " store ", int " which ");" +Registers a configuration file directive +.I token +and attaches it to +a default storage type and slot. Specifically, +.I store +and +.I which +indicate the storage slot in the data type indicated by +.I type, +where +.I type +is one of the following constants: +.BR ASN_BOOLEAN ", " ASN_INTEGER ", or " ASN_OCTET_STR . +The +.I ftype +variable indicates the file name base string searched for the +.I token +keyword. For example, the following call: +.RS +.IP +netsnmp_ds_register_config(ASN_INTEGER, "snmp", "testtoken", DS_APPLICATION_ID, 5) +.RE +.IP +would indicate that when the snmp.conf file(s) were found and parsed, +that any line beginning with the word "testtoken" should be read and +the value after "testtoken" should be stored into the +int_storage[DS_APPLICATION_ID][5] slot. For example the following +line in the configuration file: +.RS +.IP +testtoken 502 +.RE +.IP +would set int_storage[DS_APPLICATION_ID][5] = 502. This function returns +.B SNMPERR_SUCCESS +if the registration was made successfully, or +.B SNMPERR_GENERR +if the registration was not made (perhaps because the +.IR store " and " which +parameters do not correspond to a valid slot, or because of a memory +allocation failure). +.TP +.BI "int netsnmp_ds_register_premib(u_char " type ", const char *" ftype ", const char *" token ", int " store ", int " which ");" +Analogous to the preceding function, but the +.I token +is processed before MIBs are read (this is therefore useful for controlling +MIB processing options). +.SH "SEE ALSO" +.BR snmp_config "(5), " netsnmp_config_api "(3)" + diff --git a/man/default_store.3.top b/man/default_store.3.top new file mode 100644 index 0000000..cc04822 --- /dev/null +++ b/man/default_store.3.top @@ -0,0 +1,83 @@ +.TH DEFAULT_STORE 3 "25 Jun 2002" VVERSIONINFO "Net-SNMP" +.SH NAME +default_store \- generic storage of global data. +.SH SYNOPSIS +.B #include <net-snmp/net-snmp-config.h> +.br +.B #include <net-snmp/config_api.h> + +.BI "int netsnmp_ds_set_boolean(int " store ", int " which ", int " val ");" +.br +.BI "int netsnmp_ds_get_boolean(int " store ", int " which ");" +.br +.BI "int netsnmp_ds_set_int(int " store ", int " which ", int " val ");" +.br +.BI "int netsnmp_ds_get_int(int " store ", int " which ");" +.br +.BI "int netsnmp_ds_set_string(int " store ", int " which ", " +.br +.BI " const char *" val ");" +.br +.BI "char *netsnmp_ds_get_string(int " store ", int " which ");" +.br +.BI "int netsnmp_ds_register_config(u_char " type ", " +.br +.BI " const char *" ftype "," +.br +.BI " const char *" token "," +.br +.BI " int " store ", int " which ");" +.br +.BI "int netsnmp_ds_register_premib(u_char " type ", " +.br +.BI " const char *" ftype "," +.br +.BI " const char *" token "," +.br +.BI " int " store ", int " which ");" +.br +.BI "void netsnmp_ds_shutdown(void);" +.fi +.SH DESCRIPTION +The purpose of the default storage is three-fold: +.IP 1) +To create a global storage space without creating a whole bunch of +globally accessible variables or a whole bunch of access functions to +work with more privately restricted variables. +.IP 2) +To provide a single location where the thread locking needs to be +implemented. At the time of this writing, however, thread locking is not +yet in place. +.IP 3) +To reduce the number of cross dependencies between code pieces that +may or may not be linked together in the long run. This provides for a +single location in which configuration data, for example, can be +stored for a separate section of code that may not be linked in to +the application in question. +.PP +The functions defined here implement these goals. +.PP +Currently, three data types are supported: booleans, integers, and +strings. Each of these data types have separate storage +spaces. In addition, the storage space for each data type is divided +further by the application level. Currently, there are two storage +spaces. The first is reserved for the SNMP library itself. The second +is intended for use in applications and is not modified or checked by +the library, and, therefore, this is the space usable by you. +.PP +You can think of these storage spaces as being 3 arrays, something +like bool_storage[storeid][which], int_storage[storeid][which], and +string_storage[storeid][which]. The data is then accessed through the +functions defined below. For data you wish to store, you should use a +.I store +parameter of +.BR NETSNMP_DS_APPLICATION_ID . +.PP +The storage space used by the library (for which the +.I store +parameter is +.BR NETSNMP_DS_LIBRARY_ID ) +is defined in the default_store.h file, which currently contains the +following defines: +.PP +.nf diff --git a/man/encode_keychange.1.def b/man/encode_keychange.1.def new file mode 100644 index 0000000..20f5cc3 --- /dev/null +++ b/man/encode_keychange.1.def @@ -0,0 +1,71 @@ +.TH encode_keychange 1 "16 Nov 2006" VVERSIONINFO "Net-SNMP" +.SH NAME +encode_keychange - produce the KeyChange string for SNMPv3 +.SH SYNOPSIS +.B encode_keychange +\-t md5|sha1 +[\fIOPTIONS\fR] +.SH DESCRIPTION +.B encode_keychange +produces a KeyChange string using the old and new passphrases +as described in Section 5 of RFC 2274 "User-based Security Model (USM) for +version 3 of the Simple Network Management Protocol (SNMPv3)". \fB\-t\fR +option is mandatory and specifies the hash transform type to use. + +The transform is used to convert passphrase to master key for a given +user (Ku), convert master key to the localized key (Kul), and to hash the +old Kul with the random bits. + +Passphrases are obtained by examining a number of sources until success +(in order listed): +.IP +command line options (see +.B \-N +and +.B \-O +options below); +.IP +the file +.B $HOME/.snmp/passphrase.ek +which should only contain two lines with old and new passphrase; +.IP +standard input \fB\-or\-\fR user input from the terminal. +.PP + +.SH OPTIONS +.TP +\fB\-E\fR [0x]<\fIengineID\fR> EngineID used for Kul generation. +<\fIengineID\fR> is intepreted as a hex string when preceded by 0x, +otherwise it is treated as a text string. If no <\fIengineID\fR> is +specified, it is constructed from the first IP address for the local +host. +.TP +\fB\-f\fR +Force passphrases to be read from standard input. +.TP +\fB\-h\fR +Display the help message. +.TP +\fB\-N\fR "<\fInew_passphrase\fR>" +Passphrase used to generate the new Ku. +.TP +\fB\-O\fR "<\fIold_passphrase\fR>" +Passphrase used to generate the old Ku. +.TP +\fB\-P\fR +Turn off the prompt for passphrases when getting data from standard input. +.TP +\fB\-v\fR +Be verbose. +.TP +\fB\-V\fR +Echo passphrases to terminal. +.PP + +.SH "SEE ALSO" +The localized key method is defined in RFC 2274, Sections 2.6 and A.2, and +originally documented in +.IP +U. Blumenthal, N. C. Hien, B. Wijnen, +"Key Derivation for Network Management Applications", +IEEE Network Magazine, April/May issue, 1997. diff --git a/man/fixproc.1.def b/man/fixproc.1.def new file mode 100644 index 0000000..ae88a3d --- /dev/null +++ b/man/fixproc.1.def @@ -0,0 +1,40 @@ +.TH fixproc 1 "16 Nov 2006" VVERSIONINFO "Net-SNMP" +.SH NAME +fixproc - Fixes a process by performing the specified action. +.SH SYNOPSIS +.PP +.B fixproc +[\fI\-min n\fR] +[\fI\-max n\fR] +[\fI\-check | \-kill | \-restart | \-exist | \-fix\fR] +proc \.\.\. +.SH DESCRIPTION +.PP +Fixes a process named "proc" by performing the specified action. The +actions can be check, kill, restart, exist, or fix. The action is specified +on the command line or is read from a default database, which describes +the default action to take for each process. The database format and +the meaning of each action are described below. +.SH OPTIONS +.TP +.B \-min n +minimum number of processes that should be running, defaults to 1 +.TP +.B \-max n +maximum number of processes that should be running, defaults to 1 +.TP +.B \-check +check process against database /local/etc/fixproc.conf. +.TP +.B \-kill +kill process, wait 5 seconds, kill \-9 if still exist +.TP +.B \-restart +kill process, wait 5 seconds, kill \-9 if still exist, then start again +.TP +.B \-exist +checks if proc exists in ps && (min <= num. of processes <= max) +.TP +.B \-fix +check process against database /local/etc/fixproc.conf. Perform defined +action, if check fails. diff --git a/man/make_index.pl b/man/make_index.pl new file mode 100644 index 0000000..37566ba --- /dev/null +++ b/man/make_index.pl @@ -0,0 +1,70 @@ +#!/usr/bin/perl +# +# Creates a .xhtml compliant index.html file +# +my $infile = shift @ARGV; + +map { s/\.[0-9]$//; $pages{$_} = 1; } @ARGV; + +open(I,$infile); +$first = 1; +print '<p class="SectionTitle"> +Man pages +</p> +'; + +while (<I>) { + if (/^#\s*(.*)/) { + print "</table>\n" if (!$first); + print "<h2>$1</h2>\n"; + print "<table width=\"100%\">\n"; + $first = 0; + } else { + my $name = $_; + my $title; + chomp($name); + if (!exists($pages{$name})) { + print STDERR "$name is in $infile, but not in the rest of the args.\n"; + print STDERR "Make sure it's not listed twice in $infile!\n"; + } + open(H,"$name.html"); + while (<H>) { + if (/<h1>(.*?)<\/h1>/i) { + $title = $1; + } + + if (/<h2>NAME<\/h2>(.*)/i) { + $_ = $1; + + # Ignore blank lines + while (/^\s*$/) { + $_ = <H>; + } + + $title = $_; + chomp($title); + $title =~ s/\s*$name\s*-\s*//; + + # Remove any complete <> tags + $title =~ s/<.*>//i; + # Remove any half open tags + $title =~ s/<.*//i; + } + } + close(H); + print " <tr>\n"; + print " <td width=\"30%\"><a href=\"$name.html\">$name</a></td>\n"; + print " <td>$title</td>\n"; + print " </tr>\n"; + print "\n"; + delete $pages{$name}; + } +} +print '</table> +<br/>'; + +@left = keys(%pages); +if ($#left > -1) { + print STDERR "missing a filing location for: ", + join(", ", @left), "\n"; +} diff --git a/man/man_sections.txt b/man/man_sections.txt new file mode 100644 index 0000000..fcce8f9 --- /dev/null +++ b/man/man_sections.txt @@ -0,0 +1,158 @@ +# SNMP basic applications +encode_keychange +snmpcmd +snmptranslate +snmpget +snmpgetnext +snmpbulkget +snmpwalk +snmpbulkwalk +snmpset +snmptest +tkmib +# SNMP "second-level" applications +snmptable +snmpdelta +snmpusm +snmpvacm +snmpstatus +snmpnetstat +snmpdf +# Notification manual pages +snmpinform +snmptrap +snmptrapd +snmptrapd.conf +traptoemail +# SNMP application configuration manual pages +net-snmp-config +snmpconf +snmp_config +snmp.conf +# Agent manual pages +fixproc +snmpd +snmpd.conf +snmpd.examples +snmpd.internal +mib2c +mib2c.conf +mib2c-update +# SNMP base library APIs +netsnmp_library +read_config +snmp_api +mib_api +snmp_sess_api +variables +snmp_alarm +default_store +netsnmp_mib_utilities +netsnmp_debug +# Agent API manuals +add_mibdir +add_module_replacement +config_perror +config_pwarn +fprint_description +fprint_objid +fprint_value +fprint_variable +get_module_node +init_mib +init_mib_internals +netsnmp_agent +netsnmp_baby_steps +netsnmp_bulk_to_next +netsnmp_cache_handler +netsnmp_container +netsnmp_Container_iterator +netsnmp_ds_get_boolean +netsnmp_ds_get_int +netsnmp_ds_get_string +netsnmp_ds_register_config +netsnmp_ds_register_premib +netsnmp_ds_set_boolean +netsnmp_ds_set_int +netsnmp_ds_set_string +netsnmp_ds_shutdown +netsnmp_example_scalar_int +netsnmp_handler +netsnmp_instance +netsnmp_iterator_info_s +netsnmp_leaf +netsnmp_mib_handler_methods +netsnmp_mode_end_call +netsnmp_multiplexer +netsnmp_old_api +netsnmp_read_only +netsnmp_row_merge +netsnmp_scalar +netsnmp_scalar_group_group +netsnmp_serialize +netsnmp_stash_cache +netsnmp_table +netsnmp_table_array +netsnmp_table_data +netsnmp_table_dataset +netsnmp_table_iterator +netsnmp_utilities +netsnmp_watcher +print_description +print_mib +print_objid +print_value +print_variable +read_all_mibs +read_config_print_usage +read_configs +read_mib +read_module +read_module_node +read_objid +read_premib_configs +register_app_config_handler +register_app_premib_handler +register_config_handler +register_mib_handlers +register_premib_handler +send_easy_trap +send_trap_vars +send_v2trap +shutdown_mib +snmp_agent_api +snmp_alarm_register +snmp_alarm_register_hr +snmp_alarm_unregister +snmp_api_errstring +snmp_close +snmp_error +snmp_free_pdu +snmp_open +snmp_perror +snmp_read +snmp_select_info +snmp_send +snmp_sess_async_send +snmp_sess_close +snmp_sess_error +snmp_sess_init +snmp_sess_open +snmp_sess_perror +snmp_sess_read +snmp_sess_select_info +snmp_sess_send +snmp_sess_session +snmp_sess_timeout +snmp_set_mib_warnings +snmp_set_save_descriptions +snmp_timeout +snmp_trap_api +snprint_objid +snprint_value +snprint_variable +sprint_realloc_objid +sprint_realloc_value +sprint_realloc_variable +unregister_app_config_handler +unregister_config_handler
\ No newline at end of file diff --git a/man/mib2c-update.1.def b/man/mib2c-update.1.def new file mode 100644 index 0000000..52ece8a --- /dev/null +++ b/man/mib2c-update.1.def @@ -0,0 +1,28 @@ +.TH mib2c-update 1 "07 Apr 2010" VVERSIONINFO "Net-SNMP" +.SH NAME +mib2c-update - script to merge custom code into updated mib2c code +.SH SYNOPSIS +.PP +.B mib2c-update +.SH DESCRIPTION +.PP +Use mib2c-update to generate your mib2c code templates, and it will track +the original code and the changes you make to the code. If the mib2c +template changes (bug fixes, enhances in later releases), re-running +mib2c will update the template and then attempt to re-apply your +changes. +.PP +This can be extremely useful when developing your own mib2c templates. +.PP +When you first run mib2c-update, it will create several hidden +directories and a .mib2c-updaterc file. You must edit the .mib2c-udpaterc +file to specify two values. The first, UPDATE_OID, is the table name +to specify when running mib2c. The second, UPDATE_CONF, is the mib2c +configuration file to specify when running mib2c. +.PP +Additional mib2c options can be specified in UPDATE_MIB2C_OPTS. +.PP +.SH BUGS +.PP +mib2c-update has only been tested on individual tables. Specifying +a scalar or and entire MIB might not work. diff --git a/man/mib2c.1.def b/man/mib2c.1.def new file mode 100644 index 0000000..b9c1134 --- /dev/null +++ b/man/mib2c.1.def @@ -0,0 +1,227 @@ +.\" Portions of this file are subject to the following copyright. See +.\" the Net-SNMP's COPYING file for more details and other copyrights +.\" that may apply: +.\" /*********************************************************** +.\" Portions of this file are copyrighted by: +.\" Copyright Copyright 2003 Sun Microsystems, Inc. All rights reserved. +.\" Use is subject to license terms specified in the COPYING file +.\" distributed with the Net-SNMP package. +.\" ******************************************************************/ +.TH MIB2C 1 "05 Apr 2010" VVERSIONINFO "Net-SNMP" +.SH NAME +mib2c -- generate template code for extending the agent +.SH SYNOPSIS +.B mib2c +[-h] -c CONFIGFILE [-I PATH] [-f OUTNAME] [-i][-s][-q][-S VAR=VAL] MIBNODE +.SH DESCRIPTION +The mib2c tool is designed to take a portion of the MIB tree (as defined +by a MIB file) and generate the template C code necessary to implement +the relevant management objects within it. +.PP +In order to implement a new MIB module, three files are necessary: +.PP +.br +- MIB definition file +.br +- C header file +.br +- C implementation file. +.PP +The mib2c tool uses the MIB definition file to produce the two C +code files. Thus, mib2c generates a template that you can edit +to add logic necessary to obtain information from the +operating system or application to complete the module. +.PP +MIBNODE is the top level mib node you want to generate code for. +You must give mib2c a mib node (e.g. ifTable) on the command line, +not a mib file. This is the single most common mistake. +.PP +The mib2c tool accepts both SMIv1 and SMIv2 MIBs. +.PP +mib2c needs to be able to find and load a MIB file in order to generate +C code for the MIB. To enable mib2c to find the MIB file, set the +MIBS environment variable to include the MIB file you are using. +An example of setting this environment variable is: +.PP + MIBS=+NET-SNMP-TUTORIAL-MIB +.PP + or +.PP + MIBS=ALL +.PP +The first example ensures that mib2c finds the NET-SNMP-TUTORIAL-MIB +mib, in addition to the default MIB modules. The default list of MIB +modules is set when the suite is first configured and built and +basically corresponds to the list of modules that the agent supports. +The second example ensures that mib2c finds all MIBs in the search +location for MIB files. The default search location for MIB files is +DATADIR/snmp/mibs. This search location can be modified +by the MIBDIRS environment variable. +.PP +Both the MIB files to be loaded and the MIB file search location can +also be configured in the snmp.conf file. Please see snmp.conf(5) for +more information. +.PP +The generated *.c and *.h files will be created in the current working +directory. +.SH "OPTIONS" +.TP +.BI -h +Display a help message. +.TP +.BI -c " CONFIGFILE" +Use CONFIGFILE when generating code. These files will be searched for +first in the current directory and then in the DATADIR directory +(which is where the default mib2c configuration files can be found). +Running mib2c without the -c CONFIGFILE option will display +a description of the valid values for CONFIGFILE, that is, +the available config files, including new ones that you might +author. +.IP +For example, +.IP +% mib2c ifTable +.IP +will display a description of the currently available values +for CONFIGFILE. +.IP +The following values are supported for CONFIGFILE: +.IP +mib2c.mfd.conf +.br +mib2c.scalar.conf +.br +mib2c.int_watch.conf +.br +mib2c.iterate.conf +.br +mib2c.create-dataset.conf +.br +mib2c.array-user.conf +.br +mib2c.column_defines.conf +.br +mib2c.column_enums.conf +.IP +GENERATING CODE FOR SCALAR OBJECTS: +.IP +If you're writing code for some scalars, run: + + mib2c -c mib2c.scalar.conf MIBNODE +.IP +If you want to magically "tie" integer variables to integer +scalars, use: + + mib2c -c mib2c.int_watch.conf MIBNODE +.IP +GENERATING CODE FOR TABLES: + +The recommended configuration file for tables is the MIBs for +Dummies, or MFD, configuration file. It hides as much of the SNMP +details as possible, generating small, easy to understand functions. +It is also the most flexible and well documented configuration file. +See the agent/mibgroup/if-mib/ifTable/ifTable*.c files for an example: + + mib2c -c mib2c.mfd.conf MIBNODE + +If your table data is kept somewhere else (e.g. it's in the +kernel and not in the memory of the agent itself) and you need to +"iterate" over it to find the right data for the SNMP row being +accessed. See the agent/mibgroup/mibII/vacm_context.c file for an +example: + + mib2c -c mib2c.iterate.conf MIBNODE + +If your table data is kept in the agent (i.e. it's not located in +an external source) and is purely data driven (i.e. you do not need +to perform any work when a set occurs). See the +agent/mibgroup/examples/data_set.c file for an example of such a +table: + + mib2c -c mib2c.create-dataset.conf MIBNODE + +If your table data is kept in the agent (i.e. it's not located in +an external source), and you can keep your data sorted by the table +index but you do need to perform work when a set occurs: + + mib2c -c mib2c.array-user.conf MIBNODE + +GENERATING HEADER FILE DEFINITIONS + +To generate just a header with a define for each column number in +your table: + + mib2c -c mib2c.column_defines.conf MIBNODE + +To generate just a header with a define for each enum for any +column containing enums: + + mib2c -c mib2c.column_enums.conf MIBNODE + + GENERATING CODE FOR THE 4.X LINE OF CODE (THE OLDER API) + + mib2c -c mib2c.old-api.conf MIBNODE +.TP +.BI -I PATH +Search for configuration files in PATH. Multiple paths can be +specified using multiple -I switches or by using one with a comma +separated list of paths in it. +.TP +.BI -f " OUTNAME" +Places the output code into OUTNAME.c and OUTNAME.h. Normally, mib2c +will place the output code into files which correspond to the table +names it is generating code for, which is probably what you want anyway. +.TP +.BI -i +Do not run indent on the resulting code. +.TP +.BI -s +Do not look for MIBNODE.sed and run sed on the resulting code. This +is useful to shorten long mib variable names in the code. +.TP +.BI -q +Run in "quiet" mode, which minimizes the status messages +mib2c generates. +.TP +.BI -S VAR=VAL +Preset a variable VAR, in the mib2c.*.conf file, to the value +VAL. None of the existing mib2c configuration files +(mib2c.*.conf) currently makes use of this feature, however, +so this option should be considered available only for future use. +.SH EXAMPLES +.PP +The following generates C template code for the header and implementation +files to implement UCD-DEMO-MIB::ucdDemoPublic. +.IP +% mib2c -c mib2c.scalar.conf ucdDemoPublic +.br +writing to ucdDemoPublic.h +.br +writing to ucdDemoPublic.c +.br +running indent on ucdDemoPublic.h +.br +running indent on ucdDemoPublic.c +.PP +The resulting ucdDemoPublic.c and ucdDemoPublic.h files are +generated the current working directory. +.PP +The following generates C template code for the header and implementation +files for the module to implement TCP-MIB::tcpConnTable. +.IP +% mib2c -c mib2c.iterate.conf tcpConnTable +.br +writing to tcpConnTable.h +.br +writing to tcpConnTable.c +.br +running indent on tcpConnTable.h +.br +running indent on tcpConnTable.c +.PP +The resulting tcpConnTable.c and tcpConnTable.h files are generated +in the current working directory. +.PP +.SH SEE ALSO +.PP +snmpcmd(1), snmp.conf(5) diff --git a/man/mib2c.conf.5.in b/man/mib2c.conf.5.in new file mode 100644 index 0000000..3692a65 --- /dev/null +++ b/man/mib2c.conf.5.in @@ -0,0 +1,52 @@ +.TH MIB2C.CONF 5 "28 Apr 2004" VVERSIONINFO "Net-SNMP" +.SH NAME +mib2c.conf \[em] How to write mib2c.conf files to do ANYTHING based on MIB input. +.SH SYNOPSIS +% cat > mib2c.test.conf << EOF +@foreach $t table@ + Starting table $t + @foreach $c column@ + echo $t has column $c which has a syntax of $c.syntax + @end@ + +@end@ +EOF + +% mib2c \-c mib2c.test.conf internet +.SH DESCRIPTION +The mib2c.conf script language is a MIB-particular language designed +to easily process MIB nodes in ways that you want. mib2c is a +misnomer (for historical purposes), because you can produce anything +(not just C code). Look in the Net-SNMP "local" directory for a bunch +of example mib2c.*.conf files and behold the power before you. +.SH COMMANDS +.PP +All commands within mib2c.conf files are embraced by @ signs. +Anything with an @ sign at the front and back of the line is generally +supposed to be a mib2c specific command. These are detailed here: +COMMANDSHERE +.SH VARIABLES +.PP +Variables in the mib2c language look very similar to perl variables, +in that they start with a "$". They can be used for anything you +want, but most typically they'll hold mib node names being processed +by @foreach ...@ clauses. +.PP +They also have a special properties when they are a mib node, such that +adding special suffixes to them will allow them to be interpreted in +some fashion. The easiest way to understand this is through an +example. If the variable 'x' contained the word 'ifType' then some +magical things happen. In mib2c output, anytime $x is seen it is +replaced with "ifType". Additional suffixes can be used to get other +aspects of that mib node though. If $x.objectID is seen, it'll be +replaced by the OID for ifType: ".1.3.6.1.2.1.2.2.1.3". Other +suffixes that can appear after a dot are listed below. +.PP +One last thing: you can use things like $vartext immediately ending in +some other text, you can use {}s to get proper expansion of only part +of the mib2c input. IE, $xtext will produce "$xtext", but ${x}text +will produce "ifTypetext" instead. +VAREXPANSIONSHERE +.SH SEE ALSO +.PP +mib2c(1) diff --git a/man/mib2c.extract.pl b/man/mib2c.extract.pl new file mode 100644 index 0000000..14b9dea --- /dev/null +++ b/man/mib2c.extract.pl @@ -0,0 +1,43 @@ +#!/usr/bin/perl + +# read comments from mib2c and insert them in mib2c.conf.5 +my $mib2csrc = shift; + +while (<>) { + if (/COMMANDSHERE/) { + open(I,$mib2csrc); + while (<I>) { + last if (/^# which include:/); + } + while (<I>) { + last if (!/^#/); + s/^#\s+//; + # Avoid ' at the beginning of a line + s/^'/\\&'/; + # Quotes in a quoted argument must be doubled. + s/"/""/g; + s/^(\@.*\@)$/.IP "$1"/; + print; + } + close(I); + } elsif (/VAREXPANSIONSHERE/) { + open(I,$mib2csrc); + while (<I>) { + last if (/^# Mib components,/); + } + while (<I>) { + last if (!/^#/); + next if (/^#\s*$/); + s/^#\s+//; + # Avoid ' at the beginning of a line + s/^'/\\&'/; + # Quotes in a quoted argument must be doubled. + s/"/""/g; + s/^(\S+)\s+--\s+(.*)/.IP "$1"\n$2/; + print; + } + close(I); + } else { + print; + } +} diff --git a/man/net-snmp-config.1.def b/man/net-snmp-config.1.def new file mode 100644 index 0000000..3a0fa2b --- /dev/null +++ b/man/net-snmp-config.1.def @@ -0,0 +1,87 @@ +.TH net-snmp-config 1 "16 Nov 2006" VVERSIONINFO "Net-SNMP" +.SH NAME +net\-snmp\-config - returns information about installed net-snmp libraries and binaries +.SH SYNOPSIS +.PP +.B net\-snmp\-config +[OPTIONS] +.SH DESCRIPTION +.PP +The \fInet\-snmp\-config\fP shell script is designed to retrieve the +configuration information about the libraries and binaries dealing with +the Simple Network Management Protocol (SNMP), built from the +.B net-snmp +source package. The information is particularly useful for +applications that need to link against the SNMP libraries and hence +must know about any other libraries that must be linked in as well. + +.SH OPTIONS +.TP +\fB\-\-version\fR +displays the net-snmp version number +.TP +\fB\-\-indent\-options\fR +displays the indent options from the Coding Style +.TP +\fB\-\-debug\-tokens\fR +displays a example command line to search to source +code for a list of available debug tokens +.PP +SNMP Setup commands: +.TP +\fB\-\-create\-snmpv3\-user\fR [\-ro] [\-a authpass] [\-x privpass] +[\-X DES|AES] [\-A MD5|SHA] [username] +.PP +These options produce the various compilation flags needed when +building external SNMP applications: +.TP +\fB\-\-base\-cflags\fR +lists additional compilation flags needed +for external applications (excludes \fB\-I\fR. and +extra developer warning flags, if any) +.TP +\fB\-\-cflags\fR +lists additional compilation flags needed +.TP +\fB\-\-libs\fR +lists libraries needed for building applications +.TP +\fB\-\-agent\-libs\fR +lists libraries needed for building subagents +.TP +\fB\-\-netsnmp\-libs\fR +lists netsnmp specific libraries +.TP +\fB\-\-external\-libs\fR +lists libraries needed by netsnmp libs +.TP +\fB\-\-netsnmp\-agent\-libs\fR +lists netsnmp specific agent libraries +.HP +\fB\-\-external\-agent\-libs\fR lists libraries needed by netsnmp libs +.PP +Automated subagent building (produces an OUTPUTNAME binary file): +[This feature has not been extensively tested, use at your own risk.] +.TP +\fB\-\-compile\-subagent\fR OUTPUTNAME [\-\-norm] [\-\-cflags flags] +[\-\-ldflags flags] mibmodule1.c [...]] +.TP +\fB\-\-norm\fR +leave the generated .c file around to read. +.TP +\fB\-\-cflags\fR flags +extra cflags to use (e.g. \fB\-I\fR...). +.TP +\fB\-\-ldflags\fR flags +extra ld flags to use (e.g. \fB\-L\fR... \fB\-l\fR...). +.IP +Details on how the net-nsmp package was compiled: +.TP +\fB\-\-configure\-options\fR +Display original configure arguments +.TP +\fB\-\-snmpd\-module\-list\fR +Display the modules compiled into the agent +.TP +\fB\-\-prefix\fR +Display the installation prefix diff --git a/man/net-snmp-create-v3-user.1.def b/man/net-snmp-create-v3-user.1.def new file mode 100644 index 0000000..da6944c --- /dev/null +++ b/man/net-snmp-create-v3-user.1.def @@ -0,0 +1,28 @@ +.TH net-snmp-create-v3-user 1 "17 Sep 2008" VVERSIONINFO "Net-SNMP" +.SH NAME +net-snmp-create-v3-user \- create a SNMPv3 user in net-snmp configuration file +.SH SYNOPSIS +.PP +.B net-snmp-create-v3-user [-ro] [-a authpass] [-x privpass] [-X DES|AES] +.B [username] +.SH DESCRIPTION +.PP +The \fInet-snmp-create-v3-user\fP shell script is designed to create a +new user in net-snmp configuration file (/var/net-snmp/snmpd.conf by default). + +.SH OPTIONS +.TP +\fB\-\-version\fR +displays the net-snmp version number +.TP +\fB\-ro\fR +create an user with read-only permissions +.TP +\fB\-a authpass\fR +specify authentication password +.TP +\fB\-x privpass\fR +specify encryption password +.TP +\fB\-X DES|AES\fR +specify encryption algorithm diff --git a/man/netsnmp_agent_api.3.def b/man/netsnmp_agent_api.3.def new file mode 100644 index 0000000..19efd00 --- /dev/null +++ b/man/netsnmp_agent_api.3.def @@ -0,0 +1,132 @@ +.TH NETSNMP_AGENT_API 3 "13 Aug 2010" VVERSIONINFO "Net-SNMP" +.SH NAME +netsnmp_agent_api - embedding an agent into a external application +.SH SYNOPSIS +.nf +#include <net\-snmp/net\-snmp\-config.h> +#include <net\-snmp/net\-snmp\-includes.h> +#include <net\-snmp/agent/net\-snmp\-agent\-includes.h> + +int +main (int argc, char *argv[]) +{ + int agentx_subagent = 1; /* Change this if you're a master agent. */ + + snmp_enable_stderrlog(); + + /* If we're an AgentX subagent... */ + if (agentx_subagent) { + /* ...make us an AgentX client. */ + netsnmp_ds_set_boolean(NETSNMP_DS_APPLICATION_ID, + NETSNMP_DS_AGENT_ROLE, 1); + } + + init_agent("yourappname"); + + /* Initialize your MIB code here. */ + init_my_mib_code(); + + /* `yourappname' will be used to read yourappname.conf files. */ + init_snmp("yourappname"); + + /* If we're going to be a SNMP master agent... */ + if (!agentx_subagent) + init_master_agent(); /* Listen on default port (161). */ + + /* Your main loop here... */ + while (whatever) { + /* if you use select(), see snmp_api(3) */ + /* --- OR --- */ + agent_check_and_process(0); /* 0 == don't block */ + } + + /* At shutdown time: */ + snmp_shutdown("yourappname"); +} + +Then: +$(CC) ... `net\-snmp\-config \-\-agent\-libs` + +.fi +.SH DESCRIPTION +.PP +Our goal is to create a easy to use interface to the Net-SNMP package +such that you can take code that you have written that has been +designed to be a Net-SNMP MIB module and embed it into an external +application where you can either chose to be a SNMP master agent or an +AgentX sub-agent using the same MIB module code. Our suggestion is +that you use our (or another) SNMP agent as the AgentX master agent +and chose to become an AgentX subagent which then attaches to the +master. +.PP +The Net-SNMP package provides a pair of libraries that enables easy +embedding of an SNMP or AgentX agent into an external software +package. AgentX is an extensible protocol designed to allow multiple +SNMP sub-agents all run on one machine under a single SNMP master +agent. It is defined in RFC 2741. +.PP +You will need to perform a few tasks in order to accomplish +this. First off, you will need to initialize both the SNMP library and +the SNMP agent library. As indicated above, this is done slightly +differently depending on whether or not you are going to perform as a +master agent or an AgentX sub-agent. +.SH CONFIGURATION +.PP +If you intend to operate as an AgentX sub-agent, you will have to +configured the Net-SNMP package with agentx support (which is turned +on by default, so just don't turn it off) +.PP +Additionally, you will need to link against the Net-SNMP libraries +(use the output of "net\-snmp\-config \-\-agent\-libs" to get a library +list) and call subagent_pre_init() as indicated above. +.SH COMPILING +.PP +In order to make use of any of the above API, you will need to link +against at least the four libraries listed above. +.SH FUNCTIONS +.PP This is a brief description of the functions called above and +where to find out more information on them. It is certainly not a +complete list of what is available within all the Net-SNMP libraries. +.IP "snmp_enable_stderrlog()" +Logs error output from the SNMP agent to the standard error stream. +.IP "netsnmp_ds_set_boolean()" +Please see the +.IR default_store(3) +manual page for more information +about this API. +.IP "init_agent(char *name)" +Initializes the embedded agent. This should be called before the +.BR "init_snmp()" +call. +.I name +is used to dictate what .conf file to read when +.BR "init_snmp()" +is called later. +.IP "init_snmp(char *name)" +Initializes the SNMP library. Note that one of the things this will +do will be to read configuration files in an effort to configure your +application. It will attempt to read the configuration files named by +the +.I name +string that you passed in. It can be used to configure access +control, for instance. Please see the +.IR netsnmp_config_api(3) ", " snmp_config(5) ", and " snmpd.conf(5) +manual pages for further details on this subject. +.IP "init_master_agent(void)" +Initializes the master agent and causes it to listen for SNMP requests +on its default UDP port of 161. +.IP "agent_check_and_process(int block)" +This checks for packets arriving on the SNMP port and processes them +if some are found. If +.I block +is non-zero, the function call will block until a packet arrives or an +alarm must be run (see +.IR snmp_alarm(3) ). +The return value from this function is a positive integer if packets +were processed, zero if an alarm occurred and \-1 if an error occured. +.IP "snmp_shutdown(char *name);" +This shuts down the agent, saving any needed persistent storage, etc. +.SH "SEE ALSO" +http://www.net\-snmp.org/tutorial\-5/toolkit/ select(2), snmp_api(3), +default_store(3), snmp_alarm(3), netsnmp_config_api(3), snmp_config(5), +snmpd.conf(5) diff --git a/man/netsnmp_config_api.3.def b/man/netsnmp_config_api.3.def new file mode 100644 index 0000000..68049df --- /dev/null +++ b/man/netsnmp_config_api.3.def @@ -0,0 +1,373 @@ +.TH NETSNMP_CONFIG_API 3 "13 Aug 2010" VVERSIONINFO "Net-SNMP" +.SH NAME +register_config_handler, +register_const_config_handler, +register_prenetsnmp_mib_handler, +unregister_config_handler, +register_mib_handlers, +unregister_all_config_handlers, +register_app_config_handler, +register_app_prenetsnmp_mib_handler, +unregister_app_config_handler, +read_configs, +read_premib_configs, +read_config_print_usage, +config_perror, +config_pwarn - netsnmp_config_api functions +.SH SYNOPSIS +.B #include <net-snmp/config_api.h> +.br +.SS Config Handlers +.PP +.B struct config_line * +.br +.BI " register_config_handler(const char *" filePrefix ", +.br +.BI " const char *" token , +.br +.BI " void (*" parser ")(const char *, char *)," +.br +.BI " void (*" releaser ")(void)," +.br +.BI " const char *"usageLine ");" +.PP +.B struct config_line * +.br +.BI " register_const_config_handler(const char *" filePrefix ", +.br +.BI " const char *" token , +.br +.BI " void (*" parser ")(const char *, const char *)," +.br +.BI " void (*" releaser ")(void)," +.br +.BI " const char *" usageLine ");" +.PP +.PP +.B struct config_line * +.br +.BI " register_prenetsnmp_mib_handler(const char *" filePrefix ", +.br +.BI " const char *" token , +.br +.BI " void (*" parser ")(const char *, char *)," +.br +.BI " void (*" releaser ")(void)," +.br +.BI " const char *" usageLine ");" +.PP +.BI "void unregister_config_handler(const char *" filePrefix "," +.br +.BI " const char *" token ");" +.PP +.\" Defined in mib.c, rather than read_config.c +.B "void register_mib_handlers(void);" +.br +.B "void unregister_all_config_handlers(void);" +.br +.SS Application Handlers +.PP +.B struct config_line * +.br +.BI " register_app_config_handler(const char *" token , +.br +.BI " void (*" parser ")(const char *, char *)," +.br +.BI " void (*" releaser ")(void)," +.br +.BI " const char *"usageLine ");" +.PP +.B struct config_line * +.br +.BI " register_app_prenetsnmp_mib_handler(const char *" token , +.br +.BI " void (*" parser ")(const char *, char *)," +.br +.BI " void (*" releaser ")(void)," +.br +.BI " const char *" usageLine ");" +.PP +.BI "void unregister_app_config_handler(const char *" token ");" +.br +.SS Reading Configuration Files +.PP +.B "void read_premib_configs(void);" +.br +.B "void read_configs(void);" +.br +.SS Help Strings and Errors +.PP +.BI "void read_config_print_usage(char *" lead ");" +.br +.BI "void config_pwarn(const char *" string ");" +.br +.BI "void config_perror(const char *" string ");" + +.SH DESCRIPTION +The functions are a fairly extensible system of parsing various +configuration files at the run time of an application. The +configuration file flow is broken into the following phases: +.RS 4 +.TP 4 +1. +Registration of handlers. +.TP +2. +Reading of the configuration files for pre-MIB parsing requirements. +.TP +3. +Reading and parsing of the textual MIB files. +.TP +4. +Reading of the configuration files for configuration directives. +.TP +5. +Optionally re-reading the configuration files at a future date. +.RE +.PP +The idea is that the calling application is able to register +.I handlers +for certain +.I tokens +specified in certain named +.I "configuration files." +The +.B read_configs() +function can then be called to look for all relevant configuration files, +match the first word on each line against the list of registered tokens +and pass the remainder of the line to the appropriate registered handler. +.SH REGISTERING A HANDLER +.TP +.B register_config_handler() +Registers a configuration handler routine, which should be called +to process configuration directives starting with the specified token. +For example: +.PP +.RS +.RS +register_config_handler("snmp", "exampleToken", example_handler, NULL, "ARG1 [ARG2]"); +.RE +.RE +.IP +would register the +.B example_handler() +function so that it will get called every time the first word of a +line in the +.I snmp.conf +configuration file(s) matches "exampleToken". +.br +Calling the appropriate handlers to process the configuration file directives +is the responsibility of +.B read_configs() +(see below). +.TP +.B register_const_config_handler() +Similar to the +.B register_config_handler() +function, but the parser routine is explicitly constrained +to not modify the string being parsed. +.TP +.B register_prenetsnmp_mib_handler() +Similar to the +.B register_config_handler() +function, but the registered handler routine will be called +\fIbefore\fP the textual MIBs are read in. +This is typically used for tokens that will affect the configuration of +the MIB parser, and will normally only be used within the SNMP library itself. +.TP +.B register_mib_handlers() +Initialisation routine to register the internal SNMP library configuration handlers. +.TP +.B unregister_config_handler() +Removes the registered configuration handler for the specified +.I filePrefix +and +.IR token . +.TP +.B unregister_all_config_handlers() +Removes all registered configuration handlers. + +.SS Token Handlers +.PP +Handler functions should have the following signature: +.PP +.RS +.BI "void handler(const char *" token ", char *" line ");" +.br +or +.br +.BI "void handler(const char *" token ", const char *" line ");" +br +(if registered using \fIregister_const_config_handler\fP) +.RE +.PP +The function will be called with two arguments, the first being the +token that triggered the call to this function (i.e. the token used +when registering the handler), and the second +being the remainder of the configuration file line (i.e. everything +following the white space following the matched token). + +.SS Freeing Handlers +.PP +If the token handler function dynamically allocates resources when +processing a configuration entry, then these may need to be released +before re-reading the configuration files. +If the fourth parameter ( +.I releaser +) passed to +.B register_config_handler +is non-NULL, then this specifies a function to be called before +re-reading the configuration files. This function should free any +resources allocated by the token handler function and reset its notion +of the configuration to its default. The token handler function can +then safely be called again. +No arguments are passed to the resource freeing handler. +.br +Note that this function is not called when the handler is +unregistered individually (but \fIis\fP called as part of +.B unregister_all_config_handlers() +). + +.SS Application Handlers +.TP +.B register_app_config_handler() +.TP +.B register_app_prenetsnmp_mib_handler() +.TP +.B unregister_app_config_handler() +These functions are analagous to +.BR register_config_handler() ", " register_prenetsnmp_mib_handler() " and " +.B unregister_config_handler() +but do not require the file type argument (which is filled in by the +application). It is intended that MIB modules written for the agent +use these functions to allow the agent to have more control over which +configuration files are read (typically the +.I snmpd.conf +files). +.SH READING CONFIGURATION FILES +.TP +.B read_premib_configs() +.TP +.B read_configs() +These routines process the configuration files found in the +configuration search path (see below). For each entry, the +handler registered for that configuration token is called. +.PP +.B read_premib_configs() +is run before the MIB files are read in, and processes those +configuration tokens registered using +.B register_prenetsnmp_mib_handler() +(or +.B register_app_prenetsnmp_mib_handler() +). +All other entries are ignored. +.PP +.B read_configs() +is run after the MIB files have been read in, and processes those +configuration tokens registered using +.B register_config_handler() +(or +.B register_app_config_handler() +). +If it encounters a configuration token for which no handler has +been registered (either pre- or post-mib), then it will display +a warning message, and continue processing with the next line +of the configuration file. +.SS Configuration Search Path +.PP +The configuration files to be read are found by searching a list +of configuration directories for appropriately named files. +In each such directory, the library will look for files named +\fC snmp.conf\fP, +\fC snmp.local.conf\fP, +\fI app\fP\fC.conf\fP, +\fI app\fP\fC.local.conf\fP, +.br +(where \fIapp\fP is the appication-specific filePrefix used to +register configuration handlers). +It is not necessary for any or all of these files to be present +in each directory. Missing files will be silently skipped. +.br +The idea behind the two different suffixes is that the first file can +be shared (via rdist or an NFS mount) across a large number of +machines and the second file can be used to configure local settings +for one particular machine. +.PP +The default list of directories to search is \fC SYSCONFDIR/snmp\fP, +followed by \fC DATADIR/snmp\fP, +followed by \fC LIBDIR/snmp\fP, +followed by \fC $HOME/.snmp\fP. +This list can be changed by setting the environmental variable +.I SNMPCONFPATH +to be a (colon separated) list of directories to search. +.br +.SS init_snmp() +.PP +The normal mode of operation would be to register the application-specific +configuration handlers, and then invoke +.BR init_snmp() "." +This would call the routines listed above to register the internal library +configuration handlers, process any configuration tokens registered with +.B register_prenetsnmp_mib_handler(), +read in the textual MIB files using +.B init_mib(), +and finally parse the configuration file tokens registered with +.BR register_config_handler() . +.PP +If the +.B init_snmp() +function is used, none of these functions need to be explicitly +called by the application. +.SH HELP STRINGS AND ERRORS +.PP +The +.I usageLine +parameter passed to +.B register_config_handler() +and similar calls, is used to display help information when the +.B read_config_print_usage() +function is called. This function is used by all of the applications +when the +.B -H +flag is passed on the command line. It prints a summary of all of the +configuration file lines, and the associated files, that the +configuration system understands. The +.I usageLine +parameter should be a list of arguments expected after the token, and +not a lengthy description (which should go into a manual page +instead). The +.I lead +prefix will be prepended to each line that the function prints to +stderr, where it displays its output. +.PP +The +.B init_snmp() +function should be called before the +.B read_config_print_usage() +function is called, so that the library can register its configuration +file directives as well for the +.B read_config_print_usage() +function to display. +.SS Error Handling Functions +.PP +The two functions +.B config_pwarn() +and +.B config_perror() +both take an error string as an argument and print it to stderr along +with the file and line number that caused the error. A call to the +second function will also force +.B read_configs() +to eventually return with an error code indicating to it's calling +function that it should abort the operation of the application. +.SH "ENVIRONMENT VARIABLES" +.TP 10 +SNMPCONFPATH +A colon separated list of directories to search for configuration +files in. +Default: SYSCONFDIR/snmp:DATADIR/snmp:LIBDIR/snmp:$HOME/.snmp +.SH "SEE ALSO" +.BR mib_api "(3), " snmp_api (3) +.\" Local Variables: +.\" mode: nroff +.\" End: diff --git a/man/netsnmp_mib_api.3.def b/man/netsnmp_mib_api.3.def new file mode 100644 index 0000000..c253047 --- /dev/null +++ b/man/netsnmp_mib_api.3.def @@ -0,0 +1,310 @@ +.TH NETSNMP_MIB_API 3 "13 Aug 2010" VVERSIONINFO "Net-SNMP" +.SH NAME +add_mibdir, +netsnmp_init_mib, +shutdown_mib, +netsnmp_read_module, +read_mib, +read_all_mibs, +add_module_replacement, +snmp_set_mib_errors, +snmp_set_mib_warnings, +snmp_set_save_descriptions, +read_objid, +snmp_parse_oid, +get_module_node, +print_mib, +print_objid, +fprint_objid, +snprint_objid, +print_description, +fprint_description, +snprint_description - netsnmp_mib_api functions +.SH SYNOPSIS +.B #include <net\-snmp/mib_api.h> +.PP +.SS Initialisation and Shutdown +.BI "int add_mibdir(const char *" "dirname" ); +.PP +.B "void netsnmp_init_mib(void); +.\".br +.\".BI "void init_mib(void);" " (deprecated)" +.\".br +.\".BI "void init_mib_internals(void);" " (deprecated)" +.br +.B "void shutdown_mib(void); +.SS Reading and Parsing MIBs +.BI "struct tree *netsnmp_read_module(const char *" "name" ); +.br +.\".BI "struct tree *read_module(const char *" "name" ");" " (deprecated)" +.\".PP +.BI "struct tree *read_mib(const char *" "filename" ); +.br +.B "struct tree *read_all_mibs(void); +.PP +.BI "int add_module_replacement(const char *" "old_module" "," +.br +.BI " const char *" "new_module" "," +.br +.BI " const char *" "tag" ", int " "len" ); +.PP +.BI "void snmp_set_mib_warnings(int " level ); +.br +.BI "void snmp_set_mib_errors(int " level ); +.br +.BI "void snmp_set_save_descriptions(int " save ");" +.SS Searching the MIB Tree +.PP +.BI "int read_objid(const char *" "input" "," +.br +.BI " oid *" "objid" ", size_t *" "objidlen" ); +.br +.BI "oid *snmp_parse_oid(const char *" "input" "," +.br +.BI " oid *" "objid" ", size_t *" "objidlen" ); +.br +.BI "int get_module_node(const char *" "name" ", const char *" "module" "," +.br +.BI " oid *" "objid" ", size_t *" "objidlen" ); +.SS Output +.PP +.BI "void print_mib(FILE *" "fp" ); +.PP +.BI "void print_objid(const oid *" objid ", size_t " objidlen ); +.br +.BI "void fprint_objid(FILE *" fp "," +.br +.BI " const oid *" objid ", size_t " objidlen ");" +.br +.BI "int snprint_objid(char *" buf ", size_t " "len" "," +.br +.BI " const oid *" objid ", size_t " objidlen ");" +.PP +.BI "void print_description(const oid *" objid ", size_t " objidlen ", int " width ); +.br +.BI "void fprint_description(FILE *" fp "," +.br +.BI " const oid *" objid ", size_t " objidlen ", int " width ); +.br +.BI "int snprint_description(char *" buf ", size_t " "len" "," +.br +.BI " const oid *" objid ", size_t " objidlen ", int " width ); +.br +.PP +.SH DESCRIPTION +The functions dealing with MIB modules fall into four groups - those +dealing with initialisation and shutdown, with reading in and parsing +MIB files, with searching the MIB tree, and output routines. +.SS Initialisation and Shutdown +.PP +.B add_mibdir +is used to add the specified directory to the path of locations which are +searched for files containing MIB modules. +Note that this does not actually load the MIB modules located +in that directory, but is simply an initialisation step to make +them available to +.BR netsnmp_read_module . +This function returns a count of files found in the directory, or a \-1 +if there is an error. +It should be called \fIbefore\fP invoking \fBnetsnmp_init_mib\fP. +.PP +.\".B init_mib_internals +.\"sets up the internal structures, preparatory to reading in MIB +.\"modules. It should be called \fIafter\fP all calls to +.\".BR add_mibdir , +.\"and before any calls to +.\".BR netsnmp_read_module . +.\".PP +.B netsnmp_init_mib +configures the MIB directory search path (using +.B add_mibdir +), sets up the internal MIB framework, +and then loads the appropriate MIB modules (using +.BR netsnmp_read_module " and " read_mib ")." +See the ENVIRONMENTAL VARIABLES section for details. +.br +It should be called before any other +routine that manipulates or accesses the MIB tree +(but after any additional +.B add_mibdir +calls). +.PP +.B shutdown_mib +will clear the information that was gathered by +.BR netsnmp_read_module ", " add_mibdir " and " add_module_replacement . +It is strongly recommended that one does not invoke +.BR shutdown_mib +while there are SNMP sessions being actively managed. +.SS Reading and Parsing MIBs +.PP +.B netsnmp_read_module +takes the name of a MIB module (which need not be the same as the +name of the file that contains the module), locates this within the +configured list of MIB directories, and loads the definitions from +the module into the active MIB tree. +It also loads any MIB modules listed in the IMPORTS clause of this module. +.PP +.B read_mib +is similar, but takes the name of the file containing the MIB module. +Note that this file need not be located within the MIB directory +search list (although any modules listed in the IMPORTS clause do). +.PP +.B read_all_mibs +will read in all the MIB modules found on the MIB directory search list. +.PP +In general the parser is silent about what strangenesses it sees in +the MIB files. To get warnings reported, call +.B snmp_set_mib_warnings +with a +.I level +of 1 (or 2 for even more warnings). +.PP +.B add_module_replacement +can be used to allow new MIB modules to obsolete older ones, without +needing to amend the IMPORTS clauses of other modules. It takes the +names of the old and new modules, together with an indication of which +portions of the old module are affected. +.RS +.TS +tab(+); +lb lb lb +l l l. +tag + len + load the new module when: +NULL + 0 + always (the old module is a strict subset of + + + the new) +name + 0 + for the given tag only +name + non-0 + for any identifier with this prefix +.TE +.RE +It can also be used to handle errors in the module identifiers used +in MIB IMPORTS clauses (such as referring to +.I RFC1213 +instead of +.IR RFC1213\-MIB ). +.SS Searching the MIB Tree +.PP +.B read_objid +takes a string containing a textual version of an object identifier +(in either numeric or descriptor form), and transforms this into the +corresponding list of sub-identifiers. This is returned in the +.I output +parameter, with the number of sub-identifiers returned via +.IR out_len . +When called, +.I out_len +must hold the maximum length of the +.I output +array. +If multiple object identifiers are being processed, then this +length should be reset before each call. +This function returns a value of 1 if it succeeds in parsing the string +and 0 otherwise. +.PP +.B snmp_parse_oid +is similar, but returns a pointer to the parsed OID buffer (or NULL). +.PP +.B get_module_node +takes a descriptor and the name of a module, and returns the corresponding +oid list, in the same way as +.B read_objid +above. +.br +If the module name is specified as "ANY", then this routine will +assume that the descriptor given is unique within the tree, and will +return the matching entry. If this assumption is invalid, then the +behaviour as to which variable is returned is implementation +dependent. +.br +.SS Output +.B print_mib +will print out a representation of the currently active MIB tree to +the specified FILE pointer. +.PP +.B print_objid +will take an object identifier (as returned by +.BR read_objid ", " snmp_parse_oid " or " get_module_node ")," +and prints the textual form of this OID to the standard output. +.PP +.B fprint_objid +does the same, but prints to the FILE pointer specified by the initial +parameter. +.PP +.B snprint_objid +prints the same information into the buffer pointed to by +.I buf +which is of length +.IR len . +It returns the number of characters printed, or \-1 if the +buffer was not large enough. In the latter case, +.I buf +will typically contain a truncated version of the information (but +this behaviour is not guaranteed). +.PP +.BR print_description , +.BR fprint_description , +and +.B snprint_description +take a similar object identifier +and print out a version of the MIB definition for that object, +together with the full OID. The +.I width +argument controls how the OID is layed out. +.PP +By default the parser does not save descriptions since they may be +huge. In order to be able to print them, it is necessary to invoke +.BI snmp_set_save_descriptions(1) before +calling +.B init_mib +(or similar). +.SH "ENVIRONMENT VARIABLES" +.PP +The main use of environmental variables with respect to these API calls +is to configure which MIB modules should be loaded, and where they are +located. +.TP 10 +MIBDIRS +A colon separated list of directories to search for MIB modules. +.br +Default: DATADIR/snmp/mibs +.br +Used by +.BR init_mib ", " netsnmp_read_module ", " read_all_mibs +and (implicitly) by +.BR read_mib . +.TP 10 +MIBS +A colon separated list of MIB modules to load. +.br +The default list of modules will depend on how the Net-SNMP software +was originally compiled, but is typically: +IP\-MIB:IF\-MIB:TCP\-MIB:UDP\-MIB:SNMPv2\-MIB:RFC1213\-MIB: UCD\-SNMP\-MIB:HOST\-RESOURCES\-MIB +.IP +If the value of the +.B MIBS +environmental variable starts with a '+' character, +then these MIB modules will be added to the default list. +Otherwise these modules (plus any that they IMPORT from) will be loaded +.I instead +of the default list. +.IP +If the +.B MIBS +environmental variable has the value +.BR ALL " then " read_all_mibs +will be called to load the full collection of all available MIB modules. +.IP +Used by +.B init_mib +only. +.TP 10 +MIBFILES +A colon separated list of files to load. +.br +Default: (none) +.br +Used by +.B init_mib +only. +.SH "SEE ALSO" +.BR snmp_api "(3)," +.BR output_api "(3)" diff --git a/man/netsnmp_pdu_api.3.def b/man/netsnmp_pdu_api.3.def new file mode 100644 index 0000000..0b94e9e --- /dev/null +++ b/man/netsnmp_pdu_api.3.def @@ -0,0 +1,30 @@ +.TH NETSNMP_PDU_API 3 "13 Aug 2010" VVERSIONINFO "Net-SNMP" +.SH NAME +snmp_pdu_create, +snmp_clone_pdu, +snmp_fix_pdu, +snmp_free_pdu - netsnmp_pdu_api functions +.SH SYNOPSIS +.B #include <net-snmp/pdu_api.h> +.PP +.BI "netsnmp_pdu *snmp_pdu_create( int" "type" ");" +.PP +.BI "netsnmp_pdu *snmp_clone_pdu( netsnmp_pdu*" "pdu" ");" +.PP +.BI "netsnmp_pdu *snmp_fix_pdu( netsnmp_pdu*" "pdu" ", int " "idx" ");" +.PP +.BI "netsnmp_pdu *snmp_free_pdu( netsnmp_pdu*" "pdu" ");" +.PP +.SH DESCRIPTION +These functions deal with SNMP request structures. +.PP +.B snmp_pdu_create +.PP +.B snmp_clone_pdu +.PP +.B snmp_fix_pdu +.PP +.B snmp_free_pdu +.SH "SEE ALSO" +.BR varbind_api "(3)" +.BR session_api "(3)" diff --git a/man/netsnmp_sess_api.3.def b/man/netsnmp_sess_api.3.def new file mode 100644 index 0000000..36b4159 --- /dev/null +++ b/man/netsnmp_sess_api.3.def @@ -0,0 +1,235 @@ +.TH NETSNMP_SESS_API 3 "19 May 2011" VVERSIONINFO "Net-SNMP" +.SH NAME +snmp_sess_init, +snmp_sess_open, +snmp_sess_session, +snmp_sess_send, +snmp_sess_async_send, +snmp_sess_select_info, +snmp_sess_read, +snmp_sess_timeout, +snmp_sess_synch_response, +snmp_sess_close, +snmp_sess_error - session functions +.SH SYNOPSIS +.B #include <net-snmp/session_api.h> +.PP +.BI "void snmp_sess_init(struct snmp_session *" session ");" +.PP +.BI "void *snmp_sess_open(struct snmp_session *" session ");" +.PP +.BI "struct snmp_session *snmp_sess_session(void *" handle ");" +.PP +.BI "int snmp_sess_send(void *" handle ", struct snmp_pdu *" pdu ");" +.PP +.BI "int snmp_sess_async_send(void *" handle "," +.br +.BI " struct snmp_pdu *" pdu ", " +.br +.BI " snmp_callback " callback ", " +.br +.BI " void *" callbackData ");" +.PP +.BI "int snmp_sess_select_info(void *" handle "," +.br +.BI " int *" numfds ", fd_set *" fdset ", " +.br +.BI " struct timeval *" timeout ", " +.br +.BI " int *" block ");" +.PP +.BI "int snmp_sess_read(void *" handle ", fd_set *" fdset ");" +.PP +.BI "void snmp_sess_timeout(void *" handle ");" +.PP +.BI "int snmp_sess_synch_response ( void *" "handle," +.RS +.BI "netsnmp_pdu *" "pdu" ", " +.br +.BI "netsnmp_pdu **" "response" ); +.RE +.PP +.BI "int snmp_sess_close(void *" handle ");" +.PP +.BI "void snmp_sess_error(void *" handle ", int *" pcliberr ", " +.br +.BI " int *" psnmperr ", char **" pperrstring ");" +.SH DESCRIPTION +These functions define a subset of the API that can be used +to manage single SNMP sessions in a multi-threaded application. +Except for +.BR snmp_sess_session() , +these functions are single session versions of the traditional +SNMP library API. +.PP +Note that these functions use an opaque pointer +.RI ( handle +in the above prototypes) to identify a single session in lieu of a +.I session +pointer (as in the traditional API). +.PP +.B snmp_sess_init() +prepares a struct snmp_session that sources transport characteristics +and common information that will be used for a set of SNMP transactions. +After this structure is passed to +.B snmp_sess_open() +to create an SNMP session, the structure is no longer used. Instead +the opaque pointer returned by +.B snmp_sess_open() +is used to refer to that session henceforth. +.PP +SNMP sessions that are created with +.B snmp_sess_open() +are not affected by, and SHOULD NOT BE USED WITH, +.BR snmp_select_info() ", " snmp_read() ", " snmp_timeout() " nor" +.BR snmp_close() . +Rather the equivalent single session functions described here should +be used. +.PP +.B snmp_sess_init() +and +.B snmp_sess_open() +each take as input a pointer to a struct snmp_session object. +This structure contains information for a set of transactions that +will share similar transport characteristics. +.B snmp_sess_session() +takes the opaque session handle and returns a pointer to +its associated struct snmp_session. +.PP +.B snmp_sess_send() +and +.B snmp_sess_async_send() +each take a +.I pdu +parameter, which points to a struct snmp_pdu object containing +information that describes a transaction that will be performed over +an open session. +.PP +Consult snmp_api.h for the definitions of these structures. +.PP +With the +.I snmp_sess_async_send() +call, +.I snmp_sess_read +will invoke the specified callback when the response is received. +.PP +.BR snmp_sess_select_info() ", " snmp_sess_read() " and " snmp_sess_timeout() +provide an interface for the use of the +.BR select (2) +system call so that SNMP transactions for a single session can occur +asynchronously. +.PP +.B snmp_sess_select_info() +is passed the information that would have been passed to +.BR select (2) +in the absence of SNMP. For example, this might include file +descriptors associated with the main loop of a graphical +application. This information is modified so that SNMP will get the +service it requires from the call to +.BR select (2). +In this case, +.IR numfds ", " fdset " and " timeout +correspond to the +.IR nfds ", " readfds " and " timeout +arguments to +.BR select (2) +respectively. The only exception is that timeout must ALWAYS point to +an allocated (but perhaps uninitialized) +.I struct timeval +(it cannot be NULL as for +.BR select (2)). +If +.I timeout +would have been passed as NULL, +.I block +is instead set to true, and +.I timeout +is treated as undefined. This same rule applies upon return from +.BR snmp_select_info() . +.PP +After calling +.B snmp_sess_select_info() , +.BR select (2) +should be called with the returned data. When it returns, +.B snmp_sess_read() +should then be called with the +.I fd_set +returned from +.BR select (2). +This will read any input from this session's SNMP socket. If +.BR select (2) +times out (that is, it returns zero), +.B snmp_sess_timeout() +should be called to see if a timeout has occurred on the SNMP +session. +.PP +.I snmp_sess_synch_response +is a convenience routine that will send the request, +wait for the response and process it before returning. +See the descriptions of +.I "snmp_sess_send" ", " "snmp_sess_read" +etc for details. +.SH DIAGNOSTICS +.PP +Error return status from +.B snmp_sess_open() +is indicated by return of a NULL pointer. +Error return status from +.B snmp_sess_close() +and +.B snmp_sess_send() +is indicated by a return value of 0. A successful status will return +1. +.PP +Further information can be obtained by using +.B snmp_sess_error() +to see what type of error has occurred. This function returns the +SNMP +.I snmp_errno +variable, the value of the system +.I errno +variable, and a string interpretation of both variables. The string +must be freed after use by the caller. +.PP +For errors returned by +.BR snmp_sess_open() , +use the corresponding function +.B snmp_error() +instead of +.BR snmp_sess_error() . +.PP +Consult snmp_api.h for the complete set of SNMP library +error values. +The SNMP library error value +.IR snmperr +can be one of the following values: +.RS 2n +.IP SNMPERR_GENERR \w'SNMPERR_BAD_REPETITIONS'u+2n +A generic error occurred. +.IP SNMPERR_BAD_LOCPORT \w'SNMPERR_BAD_REPETITIONS'u+2n +The local port was bad because it had already been +allocated or permission was denied. +.IP SNMPERR_BAD_ADDRESS \w'SNMPERR_BAD_REPETITIONS'u+2n +The host name or address given was not useable. +.IP SNMPERR_BAD_SESSION \w'SNMPERR_BAD_REPETITIONS'u+2n +The specified session was not open. +.IP SNMPERR_TOO_LONG \w'SNMPERR_BAD_REPETITIONS'u+2n +.IP SNMPERR_NO_SOCKET \w'SNMPERR_BAD_REPETITIONS'u+2n +.IP SNMPERR_V2_IN_V1 \w'SNMPERR_BAD_REPETITIONS'u+2n +.IP SNMPERR_V1_IN_V2 \w'SNMPERR_BAD_REPETITIONS'u+2n +.IP SNMPERR_BAD_REPEATERS \w'SNMPERR_BAD_REPETITIONS'u+2n +.IP SNMPERR_BAD_REPETITIONS \w'SNMPERR_BAD_REPETITIONS'u+2n +.IP SNMPERR_BAD_ASN1_BUILD \w'SNMPERR_BAD_REPETITIONS'u+2n +.IP SNMPERR_BAD_SENDTO \w'SNMPERR_BAD_REPETITIONS'u+2n +.IP SNMPERR_BAD_RCVFROM \w'SNMPERR_BAD_REPETITIONS'u+2n +.IP SNMPERR_BAD_PARSE \w'SNMPERR_BAD_REPETITIONS'u+2n +.IP SNMPERR_BAD_VERSION \w'SNMPERR_BAD_REPETITIONS'u+2n +.IP SNMPERR_BAD_COMMUNITY \w'SNMPERR_BAD_REPETITIONS'u+2n +.IP SNMPERR_NOAUTH_DESPRIV \w'SNMPERR_BAD_REPETITIONS'u+2n +.IP SNMPERR_ABORT \w'SNMPERR_BAD_REPETITIONS'u+2n +.IP SNMPERR_UNKNOWN_PDU \w'SNMPERR_BAD_REPETITIONS'u+2n +.IP SNMPERR_TIMEOUT \w'SNMPERR_BAD_REPETITIONS'u+2n +.RE +.PP +.SH "SEE ALSO" +.BR select "(2), " snmp_api "(3), " snmp_api.h diff --git a/man/netsnmp_session_api.3.def b/man/netsnmp_session_api.3.def new file mode 100644 index 0000000..7164d36 --- /dev/null +++ b/man/netsnmp_session_api.3.def @@ -0,0 +1,281 @@ +.\" -*- nroff -*- +.\" Portions of this file are subject to the following copyright. See +.\" the Net-SNMP COPYING file for more details and other copyrights +.\" that may apply: +.\" /*********************************************************** +.\" Copyright 1989 by Carnegie Mellon University +.\" +.\" All Rights Reserved +.\" +.\" Permission to use, copy, modify, and distribute this software and its +.\" documentation for any purpose and without fee is hereby granted, +.\" provided that the above copyright notice appear in all copies and that +.\" both that copyright notice and this permission notice appear in +.\" supporting documentation, and that the name of CMU not be +.\" used in advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" +.\" CMU DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING +.\" ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL +.\" CMU BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR +.\" ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, +.\" WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, +.\" ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS +.\" SOFTWARE. +.\" ******************************************************************/ +.TH NETSNMP_SESSION_API 3 "19 May 2011" VVERSIONINFO "Net-SNMP" +.SH NAME +snmp_sess_init, +snmp_open, +snmp_send, +snmp_async_send, +snmp_select_info, +snmp_read, +snmp_timeout, +snmp_synch_response, +snmp_close, +snmp_perror, +snmp_sess_perror, +snmp_error, +snmp_api_errstring \- netsnmp_session_api functions +.SH SYNOPSIS +.B #include <net-snmp/session_api.h> +.PP +.BI "void snmp_sess_init ( netsnmp_session*" "sess" ); +.PP +.BI "netsnmp_session* snmp_open ( netsnmp_session *" "sess"); +.RS +.I /* Input parameter not used in active sessions */ +.RE +.PP +.BI "int snmp_send ( netsnmp_session *" "session," +.RS +.BI "netsnmp_pdu *" "pdu" ); +.RE +.PP +.BI "int snmp_async_send ( netsnmp_session *" "session," +.RS +.BI " netsnmp_pdu *" pdu ", " +.br +.BI " snmp_callback " callback ", " +.br +.BI " void *" callbackData ");" +.RE +.PP +.BI "int snmp_select_info ( int * " numfds, "fd_set *" fdset, +.RS +.BI "struct timeval *" timeout, "int *" block ); +.RE +.PP +.BI "void snmp_read ( fd_set *" fdset ); +.PP +.B void snmp_timeout ( void ); +.PP +.BI "int snmp_synch_response ( netsnmp_session *" "session," +.RS +.BI "netsnmp_pdu *" "pdu" ", " +.br +.BI "netsnmp_pdu **" "response" ); +.RE +.PP +.BI "int snmp_close ( netsnmp_session *" session ); +.br +.B "int snmp_close_sessions ( void ); +.PP +.SS Error Reporting +.I (Move to output_api(3)) +.br +.BI "void snmp_error ( netsnmp_session *session, +.RS +.BI "int *" pcliberr, "int *" psnmperr, "char **" pperrstring ); +.RE +.PP +.BI "char *snmp_api_errstring ( int" snmperr ); +.PP +.BI "void snmp_perror ( char *" msg ); +.RS +.I /* for parsing errors only */ +.RE +.PP +.BI "void snmp_sess_perror (char *" msg, "netsnmp_session *" sess ); +.RS +.I /* all other SNMP library errors */ +.RE +.PP +.SH DESCRIPTION +.I Snmp_sess_init +prepares a netsnmp_session that sources transport characteristics +and common information that will be used for a set of SNMP transactions. +After this structure is passed to +.I snmp_open +to create an SNMP session, the structure is not used. +.PP +.I Snmp_open +returns a pointer to a newly-formed +.I netsnmp_session +object, which the application must use to reference the +active SNMP session. +.PP +.I snmp_send +and +.I snmp_async_send() +each take as input a pointer to a +.I netsnmp_pdu +object. +This structure contains information that describes a transaction +that will be performed over an open session. +.PP +Consult snmp_api.h for the definitions of these structures. +.PP +With the +.I snmp_async_send() +call, +.I snmp_read +will invoke the specified callback when the response is received. +.PP +.I Snmp_read, snmp_select_info, +and +.I snmp_timeout +provide an interface for the use of the +.IR select(2) +system call so that SNMP transactions can occur asynchronously. +.PP +.I Snmp_select_info +is given the information that would have been passed to +.I select +in the absence of SNMP. For example, this might include window update information. +This information is modified so that SNMP will get the service it requires from the +call to +.I select. +In this case, +.I numfds, fdset, +and +.I timeout +correspond to the +.I nfds, readfds, +and +.I timeout +arguments to +.I select, +respectively. The only exception is that timeout must always point to an allocated (but perhaps uninitialized) +.I struct timeval. +If +.I timeout +would have been passed as NULL, +.I block +is set to true, and +.I timeout +is treated as undefined. This same rule applies upon return from +.I snmp_select_info. +.PP +After calling +.I snmp_select_info, select +is called with the returned data. When select returns, +.I snmp_read +should be called with the +.I fd_set +returned from +.I select +to read each SNMP socket that has input. +If +.I select +times out, +.I snmp_timeout +should be called to see if the timeout was intended for SNMP. +.PP +.I snmp_synch_response +is a convenience routine that will send the request, +wait for the response and process it before returning. +See the descriptions of +.I "snmp_send" ", " "snmp_read" +etc for details. +.SH DIAGNOSTICS +.PP +Previous versions of the library used +.IR snmp_get_errno +to read the global variable +.I snmp_errno +which may have held the error status within the SNMP library. +The existing method +.I snmp_perror +should be used to log ASN.1 coding errors only. +.PP +The new method +.I snmp_sess_perror +is provided to capture errors that occur during the processing +of a particular SNMP session. +.I Snmp_sess_perror +calls +.IR snmp_error +function to obtain the "C" library error +.I errno +, the SNMP library error +.I snmperr +, and the SNMP library detailed error message +that is associated with an error that occurred during a given session. +.PP +Note that in all cases except one, +.IR snmp_sess_perror +should be handed the +.I netsnmp_session * +pointer returned from +.IR snmp_open. +If +.IR snmp_open +returns a null pointer, pass the INPUT +.I netsnmp_session * +pointer used to call +.IR snmp_open. +.PP +Error return status from +.I snmp_close +and +.I snmp_send +is indicated by return of 0. A successful status will return a 1 for +.I snmp_close +and the request id of the packet for +.I snmp_send. +Upon successful return from +.I snmp_send +the pdu will be freed by the library. +.PP +Consult snmp_api.h for the complete set of SNMP library +error values. +The SNMP library error value +.IR snmperr +can be one of the following values: +.RS 2n +.IP SNMPERR_GENERR \w'SNMPERR_BAD_REPETITIONS'u+2n +A generic error occurred. +.IP SNMPERR_BAD_LOCPORT \w'SNMPERR_BAD_REPETITIONS'u+2n +The local port was bad because it had already been +allocated or permission was denied. +.IP SNMPERR_BAD_ADDRESS \w'SNMPERR_BAD_REPETITIONS'u+2n +The host name or address given was not useable. +.IP SNMPERR_BAD_SESSION \w'SNMPERR_BAD_REPETITIONS'u+2n +The specified session was not open. +.IP SNMPERR_TOO_LONG \w'SNMPERR_BAD_REPETITIONS'u+2n +.IP SNMPERR_NO_SOCKET \w'SNMPERR_BAD_REPETITIONS'u+2n +.IP SNMPERR_V2_IN_V1 \w'SNMPERR_BAD_REPETITIONS'u+2n +.IP SNMPERR_V1_IN_V2 \w'SNMPERR_BAD_REPETITIONS'u+2n +.IP SNMPERR_BAD_REPEATERS \w'SNMPERR_BAD_REPETITIONS'u+2n +.IP SNMPERR_BAD_REPETITIONS \w'SNMPERR_BAD_REPETITIONS'u+2n +.IP SNMPERR_BAD_ASN1_BUILD \w'SNMPERR_BAD_REPETITIONS'u+2n +.IP SNMPERR_BAD_SENDTO \w'SNMPERR_BAD_REPETITIONS'u+2n +.IP SNMPERR_BAD_PARSE \w'SNMPERR_BAD_REPETITIONS'u+2n +.IP SNMPERR_BAD_VERSION \w'SNMPERR_BAD_REPETITIONS'u+2n +.IP SNMPERR_NOAUTH_DESPRIV \w'SNMPERR_BAD_REPETITIONS'u+2n +.IP SNMPERR_ABORT \w'SNMPERR_BAD_REPETITIONS'u+2n +.IP SNMPERR_UNKNOWN_PDU \w'SNMPERR_BAD_REPETITIONS'u+2n +.IP SNMPERR_TIMEOUT \w'SNMPERR_BAD_REPETITIONS'u+2n +.RE +.PP +A string representation of the error code can be obtained with +.IR snmp_api_errstring , +and a standard error message may be printed using +.I snmp_perror +that functions like the +.I perror +standard routine. +.SH "SEE ALSO" +select(2), snmp_api.h diff --git a/man/netsnmp_trap_api.3.def b/man/netsnmp_trap_api.3.def new file mode 100644 index 0000000..424eb6d --- /dev/null +++ b/man/netsnmp_trap_api.3.def @@ -0,0 +1,58 @@ +.TH NETSNMP_TRAP_API 3 "13 Aug 2010" VVERSIONINFO "Net-SNMP" +.SH NAME +send_easy_trap, +send_trap_vars, +send_v2trap - send TRAPs or INFORMs from a Net-SNMP MIB module +.SH SYNOPSIS +.B #include <net-snmp/agent/agent_trap.h> +.PP +.BI "void send_easy_trap(int " trap ", int " specific ");" +.PP +.BI "void send_trap_vars(int " trap ", int " specific ", struct variable_list *" vars ");" +.PP +.BI "void send_v2trap(struct variable_list *" vars ");" +.SH DESCRIPTION +These three routines may be used to send traps from a MIB module +within the Net-SNMP agent (including an AgentX subagent). +.PP +.B send_easy_trap() +sends an SNMPv1 trap (or the SNMPv2 equivalent) to the list of +configured trap destinations (or "sinks"), using the provided values +for the generic trap type, and specific trap value. +.PP +.B send_trap_vars() +is similar, but appends the supplied list of variable bindings to the +traps that are sent. +.PP +.B send_v2trap() +uses the supplied list of variable bindings to form an SNMPv2 trap, +which is sent to SNMPv2-capable sinks on the configured list. An +equivalent INFORM is sent to the configuredq list of inform sinks. +Sinks that can only handle SNMPv1 traps are skipped. +.PP +The various "send_trap()" calls allow you to specify traps in different +formats. And the various "trapsink" directives allow you to specify +destinations to receive different formats. +But *all* traps are sent to *all* destinations, regardless of how they +were specified. +.nf +I.e. it's + ___ trapsink + / + send_easy_trap \___ [ Trap ] ____ trap2sink + ___ [ Generator ] + send_v2trap / [ ] ----- informsink + \____ + trapsess + +*Not* + send_easy_trap -------------------> trapsink + send_v2trap -------------------> trap2sink + ???? -------------------> informsink + ???? -------------------> trapsess +.fi +.SH WARNINGS +These routines are used to send the traps immediately they are called. +Invoking them at the appropriate time is left to the MIB module programmer. +.SH "SEE ALSO" +.BR snmpd.conf "(5), " snmptrapd "(8)" diff --git a/man/netsnmp_varbind_api.3.def b/man/netsnmp_varbind_api.3.def new file mode 100644 index 0000000..d950adb --- /dev/null +++ b/man/netsnmp_varbind_api.3.def @@ -0,0 +1,216 @@ +.TH NETSNMP_VARBIND_API 3 "13 Aug 2010" VVERSIONINFO "Net-SNMP" +.SH NAME +snmp_pdu_add_variable, +snmp_varlist_add_variable, +snmp_add_null_var, +snmp_clone_varbind, +snmp_set_var_objid, +snmp_set_var_value, +snmp_set_var_typed_value, +snmp_set_var_typed_integer, +print_variable, +fprint_variable, +snprint_variable, +print_value, +fprint_value, +snprint_value, +snmp_free_var, +snmp_free_varbind - netsnmp_varbind_api functions +.SH SYNOPSIS +.B #include <net-snmp/varbind_api.h> +.SS Creation +.PP +.B "netsnmp_variable_list *snmp_pdu_add_variable(" +.br +.BI " netsnmp_pdu *" pdu "," +.br +.BI " const oid *" objid ", size_t " objidlen "," +.br +.BI " u_char " type ", const void *" value ", size_t " len ");" +.br +.B "netsnmp_variable_list *snmp_varlist_add_variable(" +.br +.BI " netsnmp_variable_list *" varlist "," +.br +.BI " const oid *" objid ", size_t " objidlen "," +.br +.BI " u_char " type ", const void *" value ", size_t " len ");" +.br +.B "netsnmp_variable_list *snmp_add_null_var(" +.br +.BI " netsnmp_pdu *" pdu "," +.br +.BI " const oid *" objid ", size_t " objidlen ");" +.PP +.B "netsnmp_variable_list *snmp_clone_varbind(" +.br +.BI " netsnmp_variable_list *" varlist ");" +.SS Setting Values +.PP +.BI "int snmp_set_var_objid( netsnmp_variable_list* " variable "," +.br +.BI " const oid * " objid ", size_t " objidlen ");" +.br +.BI "int snmp_set_var_value( netsnmp_variable_list* " variable "," +.br +.BI " const void * " value ", size_t " vallen ");" +.br +.BI "int snmp_set_var_typed_value( netsnmp_variable_list* " variable "," +.br +.BI " u_char " type "," +.br +.BI " const void * " value ", size_t " vallen ");" +.br +.BI "int snmp_set_var_typed_integer( netsnmp_variable_list* " variable "," +.br +.BI " u_char " type ", long " value ");" +.br +.SS Output +.PP +.BI "void print_variable(const oid *" "objid" ", size_t " "objidlen" "," +.br +.BI " const netsnmp_variable_list *" variable ");" +.br +.BI "void fprint_variable(FILE *" fp "," +.br +.BI " const oid *" objid ", size_t " objidlen "," +.br +.BI " const netsnmp_variable_list *" variable ");" +.br +.BI "int snprint_variable(char *" "buf" ", size_t " "len" "," +.br +.BI " const oid *" objid ", size_t " objidlen "," +.br +.BI " const netsnmp_variable_list *" variable ");" +.PP +.BI "void print_value(const oid *" objid ", size_t " objidlen "," +.br +.BI " const netsnmp_variable_list *" variable ");" +.br +.BI "void fprint_value(FILE *" fp "," +.br +.BI " const oid *" objid ", size_t " objidlen "," +.br +.BI " const netsnmp_variable_list *" variable ");" +.br +.BI "int snprint_value(char *" buf ", size_t " "len" "," +.br +.BI " const oid *" objid ", size_t " objidlen "," +.br +.BI " const netsnmp_variable_list *" variable ");" +.br +.br +.SS Deletion +.PP +.BI "void snmp_free_var( netsnmp_variable_list *" variable ");" +.br +.BI "void snmp_free_varbind( netsnmp_variable_list *" variables ");" +.br +.PP +.SH DESCRIPTION +The functions dealing with variable bindings fall into four groups - +dealing with the creation, setting of values, output and deletion of varbinds. +.SS Creation +.B snmp_pdu_add_variable +will create a new varbind structure, initialised with the name ( +.IR objid ", " objidlen +), syntax ( +.I type +) and value ( +.I value ", " len +) provided. +This varbind is then added to the end of the varbind list in +the given PDU. +.PP +.B snmp_varlist_add_variable +is similar, but appends the new varbind to the end of the +varbind list provided. +When adding the first varbind to an empty list, simply +pass the address of the head of the list: +.IP + netsnmp_variable_list *vl = NULL; + snmp_varlist_add_variable( + &vl, name1, name1_len, + ASN_\fITYPE\fP, &val1, val1_len); + snmp_varlist_add_variable( + &vl, name2, name2_len, + ASN_\fITYPE\fP, &val2, val2_len); +.PP +In both cases, the routine will return a pointer to the new +varbind structure (or NULL if the varbind creation fails). +.PP +.B snmp_add_null_var +is a convenience function to add an empty varbind to the PDU. +without needing to specify the NULL value explicitly. +This is the normal mechanism for constructing a GET (or similar) +information retrieval request. +.br +Again, this returns a pointer to the new varbind, or NULL. +.PP +.B snmp_clone_varbind +creates a copy of each varbind in the specified list, +returning a pointer to the head of the new list +(or NULL if the cloning fails). +.br +.SS Setting of values +.B snmp_set_var_objid +sets the name of the varbind structure to the specified OID. +.br +.B snmp_set_var_typed_value +sets the syntax type and value of the varbind structure. +.br +.B snmp_set_var_value +sets the value of the varbind structure, leaving the syntax type unchanged. +.br +.B snmp_set_var_typed_integer +is a convenience function to set the syntax type and value for +a 32-bit integer-based varbind. +.PP +All four of these return 0 if the assignment is successful, +or 1 if it is not. +.SS Output +.B print_variable +will take an object identifier (as returned by +.BR read_objid ", " snmp_parse_oid " or " get_module_node ) +and an instance of such a variable, and prints to the standard output +the textual form of the object identifier together with the value +of the variable. +.PP +.B fprint_variable +does the same, but prints to the FILE pointer specified by the initial +parameter. +.PP +.B snprint_variable +prints the same information into the buffer pointed to by +.I buf +which is of length +.IR len . +It returns the number of characters printed, or -1 if the +buffer was not large enough. In the latter case, +.I buf +will typically contained a truncated version of the information (but +this behaviour is not guaranteed). This function replaces the +obsolete function +.BR sprint_variable . +.PP +.BR print_value , +.BR fprint_value , +and +.B snprint_value +do the same as the equivalent +.B print_variable +routines, but only displaying the value of the variable, without the +corresponding object identifier. +.PP +For displaying the OID of a varbind, see \fBmin_api\fP(3). +.br +.SS Deletion +.B snmp_free_var +releases all memory used by the given varbind structure. +.br +.B snmp_free_varbind +releases all memory used by each varbind structure in the varbind list provided. +.br +.SH "SEE ALSO" +.BR pdu_api "(3)" +.BR mib_api "(3)" diff --git a/man/snmp-bridge-mib.1 b/man/snmp-bridge-mib.1 new file mode 100644 index 0000000..80f2b5e --- /dev/null +++ b/man/snmp-bridge-mib.1 @@ -0,0 +1,208 @@ +'\" t +.\" Title: snmp-bridge-mib +.\" Author: Jens Osterkamp <jens@linux.vnet.ibm.com> +.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/> +.\" Date: 03/26/2010 +.\" Manual: Net-SNMP +.\" Source: http://www.ibm.com/ v6 +.\" Language: English +.\" +.TH "SNMP\-BRIDGE\-MIB" 1 "26 Mar 2010" "http://www\&.ibm\&.com/ v6" "Net\-SNMP" +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +snmp-bridge-mib \- provide Linux bridge information via SNMP +.SH "SYNOPSIS" +.HP \w'\fBsnmp\-bridge\-mib\fR\ 'u +\fBsnmp\-bridge\-mib\fR {bridge} +.SH "ARGUMENTS" +.PP +The following arguments are required: +.PP +\fBbridge\fR +.RS 4 +The name of the Linux bridge for which you want to provide information via SNMP, e\&.g\&. br0\&. +.RE +.SH "DESCRIPTION" +.PP +The snmp\-bridge\-mib is an extension to net\-snmp\&. It collects information about a bridge in a Linux system and exports them for query from other (remote) systems for management purposes\&. +.SH "CONFIGURATION:" +.PP +The preferred method of snmp\-bridge\-mib to attach to net\-snmp is agentx\&. For this to work, you will have to add the following line to /etc/snmp/snmpd\&.conf, +.sp +.if n \{\ +.RS 4 +.\} +.nf + master agentx + +.fi +.if n \{\ +.RE +.\} +.PP +restart snmpd and start snmp\-bridge\-mib\&. snmp\-bridge\-mib will then connect to the running snmpd daemon\&. +.PP +Another way of attaching snmp\-bridge\-mib to is to run it as an embedded perl module\&. You have to add +.sp +.if n \{\ +.RS 4 +.\} +.nf + perl do "path to location of snmp\-bridge\-mib" + +.fi +.if n \{\ +.RE +.\} +.PP +and restart snmpd\&. +.SH "EXAMPLE:" +.PP +Follow the instructions in this manpage and type +.sp +.if n \{\ +.RS 4 +.\} +.nf + perl /usr/bin/snmp\-bridge\-mib br0 + +.fi +.if n \{\ +.RE +.\} +.PP +You\'ll get the following output: +.sp +.if n \{\ +.RS 4 +.\} +.nf + registering at \&.1\&.3\&.6\&.1\&.2\&.1\&.17 + running as a subagent\&. + dot1qbridge agent started\&. + NET\-SNMP version 5\&.4\&.2\&.1 AgentX subagent connected + +.fi +.if n \{\ +.RE +.\} +.PP +Now it\'s time for a first test: +.sp +.if n \{\ +.RS 4 +.\} +.nf + $ export MIBS=+BRIDGE\-MIB + $ snmpwalk localhost \&.1\&.3\&.6\&.1\&.2\&.1\&.17 + +.fi +.if n \{\ +.RE +.\} +.PP +The output produced should look like +.sp +.if n \{\ +.RS 4 +.\} +.nf + BRIDGE\-MIB::dot1dStpBridgeHelloTime = INTEGER: 199 centi\-seconds + BRIDGE\-MIB::dot1dStpBridgeForwardDelay = INTEGER: 1499 centi\-seconds + BRIDGE\-MIB::dot1dStpPort\&.1 = INTEGER: 1 + BRIDGE\-MIB::dot1dStpPort\&.3 = INTEGER: 3 + BRIDGE\-MIB::dot1dStpPortPriority\&.1 = INTEGER: 32 + BRIDGE\-MIB::dot1dStpPortPriority\&.3 = INTEGER: 32 + BRIDGE\-MIB::dot1dStpPortState\&.1 = INTEGER: disabled(1) + BRIDGE\-MIB::dot1dStpPortState\&.3 = INTEGER: disabled(1) + BRIDGE\-MIB::dot1dStpPortEnable\&.1 = INTEGER: disabled(2) + BRIDGE\-MIB::dot1dStpPortEnable\&.3 = INTEGER: disabled(2) + BRIDGE\-MIB::dot1dStpPortPathCost\&.1 = INTEGER: 2 + BRIDGE\-MIB::dot1dStpPortPathCost\&.3 = INTEGER: 4 + BRIDGE\-MIB::dot1dStpPortDesignatedRoot\&.1 = STRING: "8000\&.001018382c78" + BRIDGE\-MIB::dot1dStpPortDesignatedRoot\&.3 = STRING: "8000\&.001018382c78" + BRIDGE\-MIB::dot1dStpPortDesignatedCost\&.1 = INTEGER: 0 + BRIDGE\-MIB::dot1dStpPortDesignatedCost\&.3 = INTEGER: 0 + BRIDGE\-MIB::dot1dStpPortDesignatedBridge\&.1 = STRING: "8000\&.001018382c78" + BRIDGE\-MIB::dot1dStpPortDesignatedBridge\&.3 = STRING: "8000\&.001018382c78" + BRIDGE\-MIB::dot1dStpPortDesignatedPort\&.1 = STRING: "32769" + BRIDGE\-MIB::dot1dStpPortDesignatedPort\&.3 = STRING: "32770" + BRIDGE\-MIB::dot1dStpPortPathCost32\&.1 = INTEGER: 2 + BRIDGE\-MIB::dot1dStpPortPathCost32\&.3 = INTEGER: 4 + BRIDGE\-MIB::dot1dTpLearnedEntryDiscards = Counter32: 0 + BRIDGE\-MIB::dot1dTpAgingTime = INTEGER: 300 seconds + BRIDGE\-MIB::dot1dTpFdbAddress\&.\'\&.\&.\&.8,x\' = STRING: 0:10:18:38:2c:78 + BRIDGE\-MIB::dot1dTpFdbAddress\&.\'\&.!^/B|\' = STRING: 0:21:5e:2f:42:7c + BRIDGE\-MIB::dot1dTpFdbPort\&.\'\&.\&.\&.8,x\' = INTEGER: 1 + BRIDGE\-MIB::dot1dTpFdbPort\&.\'\&.!^/B|\' = INTEGER: 3 + BRIDGE\-MIB::dot1dTpFdbStatus\&.\'\&.\&.\&.8,x\' = INTEGER: learned(3) + BRIDGE\-MIB::dot1dTpFdbStatus\&.\'\&.!^/B|\' = INTEGER: learned(3) + BRIDGE\-MIB::dot1dTpPort\&.1 = INTEGER: 1 + BRIDGE\-MIB::dot1dTpPort\&.3 = INTEGER: 3 + BRIDGE\-MIB::dot1dTpPortMaxInfo\&.1 = INTEGER: 1500 bytes + BRIDGE\-MIB::dot1dTpPortMaxInfo\&.3 = INTEGER: 1500 bytes + BRIDGE\-MIB::dot1dTpPortInFrames\&.1 = Counter32: 18082 frames + BRIDGE\-MIB::dot1dTpPortInFrames\&.3 = Counter32: 1546072 frames + BRIDGE\-MIB::dot1dTpPortOutFrames\&.1 = Counter32: 11601 frames + BRIDGE\-MIB::dot1dTpPortOutFrames\&.3 = Counter32: 10988 frames + BRIDGE\-MIB::dot1dTpPortInDiscards\&.1 = Counter32: 0 frames + BRIDGE\-MIB::dot1dTpPortInDiscards\&.3 = Counter32: 0 frames + +.fi +.if n \{\ +.RE +.\} +.SH "BUGS" +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 1." 4.2 +.\} +snmp\-bridge\-mib currently only supports one bridge which has to be specified on the commandline\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 2." 4.2 +.\} +Not all elements of RFC 4188 because they are either not available in sysfs or difficult to extract from the existing data\&. +.RE +.PP +.SH "SEE ALSO" +.PP +\fBsnmpd.conf\fR(5), +\fBNet::SNMP\fR(3) +.SH "AUTHOR" +.PP +\fBJens Osterkamp\fR <\&jens@linux\&.vnet\&.ibm\&.com\&> +.RS 4 +Developer +.RE +.SH "COPYRIGHT" +.br +Copyright \(co 2009, 2010 IBM Corp., All Rights Reserved +.br +.PP +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: +.PP +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software\&. +.PP +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT\&. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE\&. +.sp diff --git a/man/snmp.conf.5.def b/man/snmp.conf.5.def new file mode 100644 index 0000000..46203d0 --- /dev/null +++ b/man/snmp.conf.5.def @@ -0,0 +1,414 @@ +.TH SNMP.CONF 5 "21 Apr 2010" VVERSIONINFO "Net-SNMP" +.SH NAME +snmp.conf - configuration files for the Net-SNMP applications +.SH DESCRIPTION +Applications built using the Net-SNMP libraries typically use one or +more configuration files to control various aspects of their operation. +These files (\fBsnmp.conf\fR and \fBsnmp.local.conf\fR) can be located +in one of several locations, as described in the \fIsnmp_config(5)\fR +manual page. +.PP +In particular, \fCSYSCONFDIR/snmp/snmp.conf\fR is a common file, +containing the settings shared by all users of the system. +\fC~/.snmp/snmp.conf\fR is a personal file, with the settings +specific to a particular user. +.SH HOST-SPECIFIC FILES +Host-specific files may also be loaded and will be searched for if a +transport name is specified that matches a \fIPATH/hosts/HOST.conf\fR +file. For example, if you wanted a particular host to use SNMPv2c by +default you could create a ~/.snmp/hosts/NAME.conf file and in it put: +.RS +.PP +defVersion 2c +.RE +.PP +Any connections set to connect to the hostname \fINAME\fR will use +SNMPv2c. Also see the \fItransport\fR token below for additional +host-specific examples. +.PP +Host-specific configuration files are loaded at the time the +connection is opened. Thus they're generally loaded after all other +configuration files and can be used to override settings from the +generic files. +.PP +To avoid loading any host-specific config files set +"dontLoadHostConfig true" in your snmp.conf file. +.SH COMMAND-LINE OPTIONS +All of the tokens described in this file can be used on the command +line of Net-SNMP applications as well by prefixing them with "\-\-". +EG, specifying \fI\-\-dontLoadHostConfig=true\fR on the command line will +turn of loading of the host specific configuration files. +.SH IMPORTANT NOTE +Several of these directives may contain sensitive information +(such as pass phrases). Configuration files that include such +settings should only be readable by the user concerned. +.PP +As well as application-specific configuration tokens, there are +several directives that relate to standard library behaviour, +relevant to most Net-SNMP applications. Many of these correspond +to standard command-line options, which are described in the +\fIsnmpcmd(1)\fR manual page. +.PP +These directives can be divided into several distinct groups. +.SH CLIENT BEHAVIOUR +.IP "defDomain application domain" +The transport domain that should be used for a certain application type unless +something else is specified. +.IP "defTarget application domain target" +The target that should be used for connections to a certain application if the +connection should be in a specific domain. +.IP "defaultPort PORT" +defines the default UDP port that client SNMP applications will +attempt to connect to. This can be overridden by explicitly +including a port number in the \fIAGENT\fR specification. +See the \fIsnmpcmd(1)\fR manual page for more details. +.IP +If not specified, the default value for this token is 161. +.IP "transport HOSTSPECIFIER" +This special token should go into a hostname-specific configuration +file in a \fIhosts\fR sub-directory. For example if the file +\fIhosts/foo.conf\fR exists in the search path it will be loaded if a +transport name of \fIfoo\fR was used. Within the foo.conf file you may +put both general snmp.conf settings as well as a special +\fItransport\fR string to specify the destination to connect to. For +example, putting: +.RS +.IP +transport tcp:foo.example.com:9876 +.RE +.IP +in the \fIhosts/foo.conf\fR file will make applications referencing +the \fIfoo\fR hostname (e.g. \fIsnmpget\fR) to actually connect via +TCP to \fIfoo.exmaple.com\fR on port 9876. +.IP "defVersion (1|2c|3)" +defines the default version of SNMP to use. +This can be overridden using the \fB\-v\fR option. +.IP "defCommunity STRING" +defines the default community to use for SNMPv1 and SNMPv2c requests. +This can be overridden using the \fB\-c\fR option. +.\".IP "dumpPacket (1|yes|true|0|no|false)" +.IP "alias NAME DEFINITION" +Creates an aliased tied to NAME for a given transport definition. The +alias can the be referred to using an alias: prefix. Eg, a line of +"alias here udp:127.0.0.1:6161" would allow you to use a destination +host of "alias:here" instead of "udp:127.0.0.1:6161". This becomes +more useful with complex transport addresses involving IPv6 addresses, +etc. +.IP "dumpPacket yes" +defines whether to display a hexadecimal dump of the raw SNMP requests +sent and received by the application. +This is equivalent to the \fB\-d\fR option. +.IP "doDebugging (1|0)" +turns on debugging for all applications run if set to 1. +.\" +.\" XXX - why not full boolean values? +.\" what is the purpose of this directive ?? +.\" +.IP "debugTokens TOKEN[,TOKEN...]" +defines the debugging tokens that should be turned on when +\fIdoDebugging\fR is set. +This is equivalent to the \fB\-D\fR option. +.\".IP "16bitIDs (1|yes|true|0|no|false)" +.IP "16bitIDs yes" +restricts requestIDs, etc to 16-bit values. +.IP +The SNMP specifications define these ID fields as 32-bit quantities, +and the Net-SNMP library typically initialises them to random values +for security. +However certain (broken) agents cannot handle ID values greater than +2^16 - this option allows interoperability with such agents. +.IP "clientaddr [<transport-specifier>:]<transport-address>" +specifies the source address to be used by command-line applications +when sending SNMP requests. See \fIsnmpcmd(1)\fR for more information +about the format of addresses. +.IP +This value is also used by \fBsnmpd\fR when generating notifications. +.\" +.\" But not responses to an incoming request? +.\" What about snmptrapd? +.\" +.IP "clientRecvBuf INTEGER" +specifies the desired size of the buffer to be used when receiving +responses to SNMP requests. +If the OS hard limit is lower than the \fIclientRecvBuf\fR value, +then this will be used instead. +Some platforms may decide to increase the size of the buffer +actually used for internal housekeeping. +.IP +This directive will be ignored if the platforms does not support +\fIsetsockopt()\fR. +.IP "clientSendBuf INTEGER" +is similar to \fIclientRecvBuf\fR, but applies to the size +of the buffer used when sending SNMP requests. +.IP "noRangeCheck yes" +disables the validation of varbind values against the MIB definition +for the relevant OID. +This is equivalent to the \fB\-Ir\fR option. +.IP +This directive is primarily relevant to the \fBsnmpset\fR command, +but will also apply to any application that calls \fIsnmp_add_var()\fR +.\" what else ?? +with a non-NULL value. +.\" +.\" XXX - including snmpd ?? +.\" +.IP "noTokenWarnings" +disables warnings about unknown config file tokens. +.IP "reverseEncodeBER (1|yes|true|0|no|false)" +controls how the encoding of SNMP requests is handled. +.IP +The default behaviour is to encode packets starting from the end of +the PDU and working backwards. +This directive can be used to disable this behaviour, and build +the encoded request in the (more obvious) forward direction. +.IP +It should not normally be necessary to change this setting, as +the encoding is basically the same in either case - but working +backwards typically produces a slightly more efficient encoding, +and hence a smaller network datagram. +.IP "dontLoadHostConfig (1|yes|true|0|no|false)" +Specifies whether or not the host-specific configuration files are +loaded. Set to "true" to turn off the loading of the host specific +configuration files. +.IP "retries INTEGER" +Specifies the number of retries to be used in the requests. +.IP "timeout INTEGER" +Specifies the timeout in seconds between retries. +.\" +.\" XXX - It is probably about time to remove this choice! +.\" +.SH SNMPv3 SETTINGS +.IP "defSecurityName STRING" +defines the default security name to use for SNMPv3 requests. +This can be overridden using the \fB\-u\fR option. +.IP "defSecurityLevel noAuthNoPriv|authNoPriv|authPriv" +defines the default security level to use for SNMPv3 requests. +This can be overridden using the \fB\-l\fR option. +.IP +If not specified, the default value for this token is \fInoAuthNoPriv\fR. +.\" +.\" XXX - Is this correct ? +.\" +.RS +.IP "Note: +\fIauthPriv\fR is only available if the software has been compiled +to use the OpenSSL libraries. +.RE +.IP "defPassphrase STRING" +.IP "defAuthPassphrase STRING" +.IP "defPrivPassphrase STRING" +define the default authentication and privacy pass phrases to use +for SNMPv3 requests. +These can be overridden using the \fB\-A\fR and \fB\-X\fR options respectively. +.IP +The +.B defPassphrase +value will be used for the authentication and/or privacy pass phrases +if either of the other directives are not specified. +.IP "defAuthType MD5|SHA" +.IP "defPrivType DES|AES" +define the default authentication and privacy protocols to use for +SNMPv3 requests. +These can be overridden using the \fB\-a\fR and \fB\-x\fR options respectively. +.IP +If not specified, SNMPv3 requests will default to MD5 authentication +and DES encryption. +.RS +.IP "Note: +If the software has not been compiled to use the OpenSSL libraries, +then only MD5 authentication is supported. +Neither SHA authentication nor any form of encryption will be available. +.RE +.IP "defContext STRING" +defines the default context to use for SNMPv3 requests. +This can be overridden using the \fB\-n\fR option. +.IP +If not specified, the default value for this token is the default context +(i.e. the empty string ""). +.IP "defSecurityModel STRING" +defines the security model to use for SNMPv3 requests. +The default value is "usm" which is the only widely +used security model for SNMPv3. +.IP "defAuthMasterKey 0xHEXSTRING" +.IP "defPrivMasterKey 0xHEXSTRING" +.IP "defAuthLocalizedKey 0xHEXSTRING" +.IP "defPrivLocalizedKey 0xHEXSTRING" +define the (hexadecimal) keys to be used for SNMPv3 secure communications. +SNMPv3 keys are frequently derived from a passphrase, as discussed in +the \fIdefPassphrase\fR section above. However for improved security a +truely random key can be generated and used instead (which would +normally has better entropy than a password unless it is +amazingly long). +The directives are equivalent to the short-form +command line options \fB\-3m\fR, \fB\-3M\fR, \fB\-3k\fR, and \fB\-3K\fR. +.IP +Localized keys are +master keys which have been converted to a unique key which is only +suitable for on particular SNMP engine (agent). The length of the key +needs to be appropriate for the authentication or encryption type +being used (auth keys: MD5=16 bytes, SHA1=20 bytes; +priv keys: DES=16 bytes (8 +bytes of which is used as an IV and not a key), and AES=16 bytes). +.IP "sshtosnmpsocket PATH" +Sets the path of the \fBsshtosnmp\fR socket created by an application +(e.g. snmpd) listening for incoming ssh connections through the +\fBsshtosnmp\fR unix socket. +.IP "sshtosnmpsocketperms MODE [OWNER [GROUP]]" +Sets the mode, owner and group of the \fBsshtosnmp\fR socket created by +an application (e.g. \fBsnmpd\fR) listening for incoming ssh connections +through the \fBsshtosnmp\fR unix socket. The socket needs to be read/write +privileged for SSH users that are allowed to connect to the SNMP +service (VACM access still needs to be granted as well, most likely +through the TSM security model). +.IP "sshusername NAME" +Sets the SSH user name for logging into the remote system. +.IP "sshpubkey FILE" +Set the public key file to use when connecting to a remote system. +.IP "sshprivkey FILE" +Set the private key file to use when connecting to a remote system. +.\" +.\" XXX - are these lengths still correct ? +.\" +.SH SERVER BEHAVIOUR +.IP "persistentDir DIRECTORY" +defines the directory where \fBsnmpd\fR and \fBsnmptrapd\fR store +persistent configuration settings. +.IP +If not specified, the persistent directory defaults to +PERSISTENT_DIRECTORY +.IP "noPersistentLoad yes" +.IP "noPersistentSave yes" +disable the loading and saving of persistent configuration information. +.RS +.IP "Note:" +This will break SNMPv3 operations (and other behaviour that relies +on changes persisting across application restart). Use With Care. +.RE +.IP "tempFilePattern PATTERN" +defines a filename template for creating temporary files, +for handling input to and output from external shell commands. +Used by the \fImkstemp()\fR and \fImktemp()\fR functions. +.IP +If not specified, the default pattern is \fCNETSNMP_TEMP_FILE_PATTERN\fR. +.IP "serverRecvBuf INTEGER" +specifies the desired size of the buffer to be used when receiving +incoming SNMP requests. +If the OS hard limit is lower than the \fIserverRecvBuf\fR value, +then this will be used instead. +Some platforms may decide to increase the size of the buffer +actually used for internal housekeeping. +.IP +This directive will be ignored if the platforms does not support +\fIsetsockopt()\fR. +.IP "serverSendBuf INTEGER" +is similar to \fIserverRecvBuf\fR, but applies to the size +of the buffer used when sending SNMP responses. +.SH MIB HANDLING +.IP "mibdirs DIRLIST" +specifies a list of directories to search for MIB files. +This operates in the same way as the \fB\-M\fR option - +see \fIsnmpcmd(1)\fR for details. +Note that this value can be overridden by the +.B MIBDIRS +environment variable, and the \fB\-M\fR option. +.IP "mibs MIBLIST" +specifies a list of MIB modules (not files) that should be loaded. +This operates in the same way as the \fB\-m\fR option - +see \fIsnmpcmd(1)\fR for details. +Note that this list can be overridden by the +.B MIBS +environment variable, and the \fB\-m\fR option. +.IP "mibfile FILE" +specifies a (single) MIB file to load, in addition to the +list read from the \fImibs\fR token (or equivalent configuration). +Note that this value can be overridden by the +.B MIBFILES +environment variable. +.IP "showMibErrors (1|yes|true|0|no|false)" +whether to display MIB parsing errors. +.IP "commentToEOL (1|yes|true|0|no|false)" +whether MIB parsing should be strict about comment termination. +Many MIB writers assume that ASN.1 comments extend to the end of +the text line, rather than being terminated by the next "\-\-" token. +This token can be used to accept such (strictly incorrect) MIBs. +.br +Note that this directive was previous (mis-)named \fIstrictCommentTerm\fR, +but with the reverse behaviour from that implied by the name. +This earlier token is still accepted for backwards compatibility. +.IP "mibAllowUnderline (1|yes|true|0|no|false)" +whether to allow underline characters in MIB object names and +enumeration values. +This token can be used to accept such (strictly incorrect) MIBs. +.IP "mibWarningLevel INTEGER" +the minimum warning level of the warnings printed by the MIB parser. +.SH OUTPUT CONFIGURATION +.IP "logTimestamp (1|yes|true|0|no|false)" +Whether the commands should log timestamps with their error/message +logging or not. Note that output will not look as pretty with +timestamps if the source code that is doing the logging does +incremental logging of messages that are not line buffered before +being passed to the logging routines. This option is only used when file logging is active. +.IP "printNumericEnums (1|yes|true|0|no|false)" +Equivalent to +.BR \-Oe . +.IP "printNumericOids (1|yes|true|0|no|false)" +Equivalent to +.BR \-On . +.IP "dontBreakdownOids (1|yes|true|0|no|false)" +Equivalent to +.BR \-Ob . +.IP "escapeQuotes (1|yes|true|0|no|false)" +Equivalent to +.BR \-OE . +.IP "quickPrinting (1|yes|true|0|no|false)" +Equivalent to +.BR \-Oq . +.IP "printValueOnly (1|yes|true|0|no|false)" +Equivalent to +.BR \-Ov . +.IP "dontPrintUnits (1|yes|true|0|no|false)" +Equivalent to +.BR \-OU . +.IP "numericTimeticks (1|yes|true|0|no|false)" +Equivalent to +.BR \-Ot . +.IP "printHexText (1|yes|true|0|no|false)" +Equivalent to +.BR \-OT . +.IP "hexOutputLength integer" +Specifies where to break up the output of hexadecimal strings. +Set to 0 to disable line breaks. Defaults to 16. +.IP "suffixPrinting (0|1|2)" +The value 1 is equivalent to +.B \-Os +and the value 2 is equivalent to +.BR \-OS . +.IP "oidOutputFormat (1|2|3|4|5|6)" +Maps \-O options as follow: \-Os=1, \-OS=2, \-Of=3, \-On=4, \-Ou=5. +The value 6 has no matching \-O option. It suppresses output. +.IP "extendedIndex (1|yes|true|0|no|false)" +Equivalent to +.BR \-OX . +.IP "noDisplayHint (1|yes|true|0|no|false)" +Disables the use of DISPLAY-HINT information when parsing indices and +values to set. Equivalent to +.BR \-Ih . +.SH FILES +.IP "System-wide configuration files:" +SYSCONFDIR/snmp/snmp.conf +.br +SYSCONFDIR/snmp/snmp.local.conf +.IP "User-specific configuration settings:" +$HOME/.snmp/snmp.conf +.br +$HOME/.snmp/snmp.local.conf +.IP "Destination host specific files: +SYSCONFDIR/snmp/hosts/HOSTNAME.conf +.br +$HOME/.snmp/hosts/HOSTNAME.conf + +.SH "SEE ALSO" +snmp_config(5), netsnmp_config_api(3), snmpcmd(1). +.\" Local Variables: +.\" mode: nroff +.\" End: diff --git a/man/snmp_alarm.3.def b/man/snmp_alarm.3.def new file mode 100644 index 0000000..6c79a20 --- /dev/null +++ b/man/snmp_alarm.3.def @@ -0,0 +1,170 @@ +.TH SNMP_ALARM 3 "01 Aug 2002" VVERSIONINFO "Net-SNMP" +.SH NAME +snmp_alarm_register, +snmp_alarm_register_hr, +snmp_alarm_unregister - alarm functions +.SH SYNOPSIS +.B #include <net-snmp/utilities.h> +.PP +.B "unsigned int" +.br +.BI "snmp_alarm_register(unsigned int " seconds "," +.br +.BI " unsigned int " flags "," +.br +.BI " SNMPAlarmCallback *" f_callback "," +.br +.BI " void *" clientarg ");" +.PP +.B "unsigned int" +.br +.BI "snmp_alarm_register_hr(struct timeval " t "," +.br +.BI " unsigned int " flags "," +.br +.BI " SNMPAlarmCallback *" f_callback "," +.br +.BI " void *" clientarg ");" +.PP +.B "void +.br +.BI "snmp_alarm_unregister(unsigned int " reg ");" +.SH DESCRIPTION +.PP +These functions implement support for a generic timer handling +mechanism for multiple parts of an application to register function +callbacks to happen at a particular time in the future. +.SH USAGE +.PP +The usage is fairly simple and straight-forward: Simply create a +function you want called back at some point in the future. The +function definition should be similar to: +.RS 4 +.PP +.BI "void my_callback(unsigned int " reg ", void *" clientarg ");" +.RE +.PP +Then, call +.B snmp_alarm_register() +to register your callback to be called +.I seconds +from now. The +.I flags +field should either be +.I SA_REPEAT +or +.I NULL. +If flags is set with +.I SA_REPEAT, +then the registered callback function will be called every +.I seconds. +If +.I flags +is +.I NULL +then the function will only be called once and then removed from the +alarm system registration. +.PP +The +.I clientarg +parameter in the registration function is used only by +the client function and is stored and passed back directly to them on +every call to the system. +.PP +The +.B snmp_alarm_register() +function returns a unique +.I "unsigned int" +(which is also passed as the first argument of each callback), which +can then be used to remove the callback from the queue at a later +point in the future using the +.B snmp_alarm_unregister() +function. If the +.B snmp_alarm_register() +call fails it returns zero. In particular, note that it is entirely +permissible for an alarm function to unregister itself. +.PP +The +.B snmp_alarm_register_hr() +function is identical in operation to the +.B snmp_alarm_register() +function, but takes a +.I "struct timeval" +as a first parameter, and schedules the callback after the period +represented by +.I t +(the letters +.B hr +stand for "high resolution"). The operation of this function is +dependent on the provision of the +.BR setitimer (2) +system call by the operating system. If this system call is not +available, the alarm will be scheduled as if +.B snmp_alarm_register() +had been called with a first argument equal to the value of the +.I tv_sec +member of +.IR "t". +See, however, the notes below. +.SH INITIALIZATION +The +.B init_snmp() +function initialises the snmp_alarm subsystem by calling +.B init_snmp_alarm() +and then +.B init_alarm_post_config() +to set up the first timer to initialise the callback function. These +two functions should not be used directly by applications. +.SH "NOTES" +The default behaviour of the snmp_alarm subsystem is to request +.I SIGALRM +signals from the operating system via the +.BR alarm (2) +or +.BR setitimer (2) +system calls. This has the disadvantage, however, that no other part +of the application can use the +.I SIGLARM +functionality (or, if some other part of the application +.I does +use the +.I SIGALRM +functionality, the snmp_alarm subsystem will not work correctly). +.PP +If your application runs a +.BR select (2)-based +event loop, however, there is no need to use +.I SIGALRM +for the snmp_alarm subsystem, leaving it available for other parts of +the application. This is done by making the following call: +.PP +.nf +netsnmp_ds_set_boolean(NETSNMP_DS_LIBRARY_ID, + NETSNMP_DS_LIB_ALARM_DONT_USE_SIG, 1); +.fi +.PP +before calling +.BR "init_snmp()". +Then, +.BR snmp_select_info() +takes alarms into account when calculating the timeout value to be +used for +.BR select (2). +All you need to do is call +.BR run_alarms() +when +.BR select (2) +times out (return value of zero). This is the approach taken in the +agent; see +.IR "snmpd.c". +Furthermore, when using this method, high resolution alarms do not +depend on the presence of the +.BR setitimer (2) +system call, although overall precision is of course still determined +by the underlying operating system. Recommended. +.SH "SEE ALSO" +.BR netsnmp_session_api "(3), " default_store "(3), " +.BR alarm "(2), " setitimer "(2), " select "(2)" +.\" Local Variables: +.\" mode: nroff +.\" End: diff --git a/man/snmp_config.5.def b/man/snmp_config.5.def new file mode 100644 index 0000000..413a334 --- /dev/null +++ b/man/snmp_config.5.def @@ -0,0 +1,202 @@ +.TH SNMP_CONFIG 5 "08 Mar 2010" VVERSIONINFO "Net-SNMP" +.SH NAME +snmp_config - handling of Net-SNMP configuration files +.SH DESCRIPTION +The Net-SNMP package uses various configuration files to configure its +applications. This manual page merely describes the overall nature of +them, so that the other manual pages don't have to. +.SH "DIRECTORIES SEARCHED" +First off, there are numerous places that configuration files can be +found and read from. By default, the applications look for +configuration files in the following 4 directories, in order: +SYSCONFDIR/snmp, +DATADIR/snmp, LIBDIR/snmp, and $HOME/.snmp. In each of these +directories, it looks for files with the extension of both +.IR conf " and " local.conf +(reading the second ones last). In this manner, there are +8 default places a configuration file can exist for any given +configuration file type. +.PP +Additionally, the above default search path can be overridden by +setting the environment variable SNMPCONFPATH to a colon-separated +list of directories to search for. The path for the persistent +data should be included when running applications that use +persistent storage, such as snmpd. +.PP +Applications will read persistent configuration files +in the following order of preference: +.RS +.PP +file in +.B SNMP_PERSISTENT_FILE +environment variable +.br +directories in +.B SNMPCONFPATH +environment variable +.br +directory defined by +.B +persistentDir +snmp.conf variable +.br +directory in +.B +SNMP_PERSISTENT_DIR +environment variable +.br +default +.B +PERSISTENT_DIRECTORY +directory +.RE +.PP +Finally, applications will write persistent configuration files +in the following order of preference: +.RS +.PP +file in +.B SNMP_PERSISTENT_FILE +environment variable +.br +directory defined by +.B +persistentDir +snmp.conf variable +.br +directory in +.B +SNMP_PERSISTENT_DIR +environment variable +.br +default +.B +PERSISTENT_DIRECTORY +directory +.RE +.PP +Note: When using SNMP_PERSISTENT_FILE, the filename should match the +application name. For example, /var/net-snmp/snmpd.conf. +.SH "CONFIGURATION FILE TYPES" +Each application may use multiple configuration files, which will +configure various different aspects of the application. For instance, +the SNMP agent +.RB ( snmpd ) +knows how to understand configuration +directives in both the snmpd.conf and the snmp.conf files. In fact, +most applications understand how to read the contents of the snmp.conf +files. Note, however, that configuration directives understood in one +file may not be understood in another file. For further information, +read the associated manual page with each configuration file type. +Also, most of the applications support a +.B -H +switch on the command line that will list the configuration files it +will look for and the directives in each one that it understands. +.PP +The snmp.conf configuration file is intended to be a application suite +wide configuration file that supports directives that are useful for +controlling the fundamental nature of all of the SNMP applications, +such as how they all manipulate and parse the textual SNMP MIB files. +.SH "SWITCHING CONFIGURATION TYPES IN MID-FILE" +It's possible to switch in mid-file the configuration type that the +parser is supposed to be reading. Since that sentence doesn't make +much sense, lets give you an example: say that you wanted to turn on +packet dumping output for the agent by default, but you didn't want to +do that for the rest of the applications (ie, snmpget, snmpwalk, ...). +Normally to enable packet dumping in the configuration file +you'd need to put a line like: +.PP +.RS +dumpPacket true +.RE +.PP +into the snmp.conf file. But, this would turn it on for all of the +applications. So, instead, you can put the same line in the +snmpd.conf file so that it only applies to the snmpd daemon. However, +you need to tell the parser to expect this line. You do this by +putting a special type specification token inside a [] set. In other +words, inside your snmpd.conf file you could put the above snmp.conf +directive by adding a line like so: +.PP +.RS +[snmp] dumpPacket true +.RE +.PP +This tells the parser to parse the above line as if it were inside a +snmp.conf file instead of an snmpd.conf file. If you want to parse a +bunch of lines rather than just one then you can make the context +switch apply to the remainder of the file or until the next context +switch directive by putting the special token on a line by itself: +.PP +.RS +.nf +# make this file handle snmp.conf tokens: +[snmp] +dumpPacket true +logTimestamp true +# return to our original snmpd.conf tokens: +[snmpd] +rocommunity mypublic +.fi +.RE +.PP +The same approach can be used to set configuration directives for a +particular client application (or group of applications). For example, +any program that uses the 'snmp_parse_args()' call to handle command-line +arguments (including the standard command-line tools shipped as part of the +Net-SNMP distributions) will automatically read the config file 'snmpapp.conf'. +To set library-level settings for these applications (but not other +more-specific tools), use configuration such as the following: +.PP +.RS +[snmp] defCommunity myCommunity +.RE +.PP +for a single directive, or +.PP +.RS +.nf +# make this file handle snmp.conf tokens: +[snmp] +defCommunity myCommunity +defVersion 2c +# return to our original snmpapp.conf tokens: +[snmpapp] +.fi +.RE +.PP +for multiple settings. +Similarly for any other application token (as passed to init_snmp()). +.SH COMMENTS +.PP +Any lines beginning with the character '#' in the configuration files +are treated as a comment and are not parsed. +.SH "INCLUDING OTHER CONFIGURATION FILES" +It is possible to include other configuration files for processing +during normal configuration file processing.: +.PP +.RS +.nf +# include site specific config +include site.conf +.RE +.PP +This will search every directory in the configuration path for files +named site.conf, and will process those files before returning to the +processing of the original file. Note that if '.conf' is omitted, +it will be appended. That is, all configuration files must end +in '.conf'. +.SH "API INTERFACE" +.PP +Information about writing C code that makes use of this system in +either the agent's MIB modules or in applications can be found in the +.I netsnmp_config_api(3) +manual page. +.SH "SEE ALSO" +snmpconf(1), +netsnmp_config_api(3), +snmp.conf(5), +snmpd.conf(5) +.\" Local Variables: +.\" mode: nroff +.\" End: diff --git a/man/snmpbulkget.1.def b/man/snmpbulkget.1.def new file mode 100644 index 0000000..25210f3 --- /dev/null +++ b/man/snmpbulkget.1.def @@ -0,0 +1,64 @@ +.TH SNMPBULKGET 1 "01 May 2002" VVERSIONINFO "Net-SNMP" +.SH NAME +snmpbulkget - communicates with a network entity using SNMP GETBULK requests. +.SH SYNOPSIS +.B snmpbulkget +[COMMON OPTIONS] [-Cn <num>] [-Cr <NUM>] AGENT OID [OID]... +.SH DESCRIPTION +.B snmpbulkget +is an SNMP application that uses the SNMP GETBULK request to query a +network entity efficiently for information. One or more object +identifiers (OIDs) may be given as arguments on the command line. +Each variable name is given in the format specified in +.IR variables(5) . +.PP +If the network entity has an error processing the request packet, an +error packet will be returned and a message will be shown, helping to +pinpoint why the request was malformed. +.SH OPTIONS +.TP 8 +.BI \-Cn <NUM> +Set the +.I non-repeaters +field in the GETBULK PDU. This specifies the number of supplied +variables that should not be iterated over. The default is 0. +.TP +.BI \-Cr <NUM> +Set the +.I max-repetitions +field in the GETBULK PDU. This specifies the maximum number of +iterations over the repeating variables. The default is 10. +.PP +In addition to these options, +.B snmpbulkget +takes the common options described in the +.I snmpcmd(1) +manual page. +Note that +.B snmpbulkget +REQUIRES an argument specifying the agent to query +and at least one OID argument, as described there. +.SH EXAMPLE +The command: +.PP +snmpbulkget \-v2c \-Cn1 \-Cr5 \-Os \-c public zeus system ifTable +.PP +will retrieve the variable system.sysDescr.0 (which is the +lexicographically next object to system) and the first 5 objects in +the ifTable: +.PP +sysDescr.0 = STRING: "SunOS zeus.net.cmu.edu 4.1.3_U1 1 sun4m" +.br +ifIndex.1 = INTEGER: 1 +.br +ifIndex.2 = INTEGER: 2 +.br +ifDescr.1 = STRING: "lo0" +.br +et cetera. +.SH NOTE +As the name implies, +.B snmpbulkget +utilizes the SNMP GETBULK message, which is not available in SNMPv1. +.SH "SEE ALSO" +snmpcmd(1), variables(5), RFC 1905. diff --git a/man/snmpbulkwalk.1.def b/man/snmpbulkwalk.1.def new file mode 100644 index 0000000..c5f4a06 --- /dev/null +++ b/man/snmpbulkwalk.1.def @@ -0,0 +1,134 @@ +.\" -*- nroff -*- +.\" Portions of this file are subject to the following copyright. See +.\" the Net-SNMP COPYING file for more details and other copyrights +.\" that may apply: +.\" /*********************************************************** +.\" Copyright 1988, 1989 by Carnegie Mellon University +.\" +.\" All Rights Reserved +.\" +.\" Permission to use, copy, modify, and distribute this software and its +.\" documentation for any purpose and without fee is hereby granted, +.\" provided that the above copyright notice appear in all copies and that +.\" both that copyright notice and this permission notice appear in +.\" supporting documentation, and that the name of CMU not be +.\" used in advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" +.\" CMU DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING +.\" ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL +.\" CMU BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR +.\" ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, +.\" WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, +.\" ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS +.\" SOFTWARE. +.\" ******************************************************************/ +.TH SNMPBULKWALK 1 "01 May 2002" VVERSIONINFO "Net-SNMP" +.SH NAME +snmpbulkwalk - retrieve a subtree of management values using SNMP GETBULK requests +.SH SYNOPSIS +.B snmpbulkwalk +[APPLICATION OPTIONS] [COMMON OPTIONS] AGENT [OID] +.SH DESCRIPTION +.B snmpbulkwalk +is an SNMP application that uses SNMP GETBULK requests to query a +network entity efficiently for a tree of information. +.PP +An object identifier (OID) may be given on the command line. This OID +specifies which portion of the object identifier space will be +searched using GETBULK requests. All variables in the subtree below +the given OID are queried and their values presented to the user. +Each variable name is given in the format specified in +.IR variables(5) . +If no OID argument is present, +.B snmpbulkwalk +will search MIB\-2. +.PP +If the network entity has an error processing the request packet, an +error packet will be returned and a message will be shown, helping to +pinpoint why the request was malformed. +.PP +If the tree search causes attempts to search beyond the end of the +MIB, the message "End of MIB" will be displayed. +.SH OPTIONS +.TP 8 +.B \-Cc +Do not check whether the returned OIDs are increasing. Some agents +(LaserJets are an example) return OIDs out of order, but can +complete the walk anyway. Other agents return OIDs that are out of +order and can cause +.B snmpbulkwalk +to loop indefinitely. By default, +.B snmpbulkwalk +tries to detect this behavior and warns you when it hits an agent +acting illegally. Use +.B \-Cc +to turn off this behaviour. +.TP +.B \-Ci +Include the given OID in the search range. Normally +.B snmpbulkwalk +uses GETBULK requests starting with the OID you specified and returns +all results in the MIB tree after that OID. Sometimes, you may wish +to include the OID specified on the command line in the printed +results if it is a valid OID in the tree itself. This option lets you +do this. +.TP +.BI \-Cn <NUM> +Set the +.I non-repeaters +field in the GETBULK PDUs. This specifies the number of supplied +variables that should not be iterated over. The default is 0. +.TP +.B \-Cp +Upon completion of the walk, print the number of variables found. +.TP +.BI \-Cr <NUM> +Set the +.I max-repetitions +field in the GETBULK PDUs. This specifies the maximum number of +iterations over the repeating variables. The default is 10. +.PP +In addition to these options, +.B snmpbulkwalk +takes the common options described in the +.I snmpcmd(1) +manual page. +Note that +.B snmpbulkget +REQUIRES an argument specifying the agent to query +and at most one OID argument, as described above. +.SH EXAMPLE +The command: +.PP +snmpbulkwalk \-v2c \-Os \-c public zeus system +.PP +will retrieve all of the variables under system: +.PP +sysDescr.0 = STRING: "SunOS zeus.net.cmu.edu 4.1.3_U1 1 sun4m" +.br +sysObjectID.0 = OID: enterprises.hp.nm.hpsystem.10.1.1 +.br +sysUpTime.0 = Timeticks: (155274552) 17 days, 23:19:05 +.br +sysContact.0 = STRING: "" +.br +sysName.0 = STRING: "zeus.net.cmu.edu" +.br +sysLocation.0 = STRING: "" +.br +sysServices.0 = INTEGER: 72 +.PP +In contrast to +.BR snmpwalk , +this information will typically be gathered in a single transaction +with the agent, rather than one transaction per variable found. +.B snmpbulkwalk +is thus more efficient in terms of network utilisation, which may be +especially important when retrieving large tables. +.SH NOTE +As the name implies, +.B snmpbulkwalk +utilizes the SNMP GETBULK message, which is not available in SNMP v1. +.SH "SEE ALSO" +snmpcmd(1), variables(5). diff --git a/man/snmpcmd.1.def b/man/snmpcmd.1.def new file mode 100644 index 0000000..bb4ed96 --- /dev/null +++ b/man/snmpcmd.1.def @@ -0,0 +1,916 @@ +.\" -*- nroff -*- +.\" Portions of this file are subject to the following copyright. See +.\" the Net-SNMP COPYING file for more details and other copyrights +.\" that may apply: +.\"/*********************************************************** +.\" Copyright 1988, 1989 by Carnegie Mellon University +.\" +.\" All Rights Reserved +.\" +.\" Permission to use, copy, modify, and distribute this software and its +.\" documentation for any purpose and without fee is hereby granted, +.\" provided that the above copyright notice appear in all copies and that +.\" both that copyright notice and this permission notice appear in +.\" supporting documentation, and that the name of CMU not be +.\" used in advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" +.\" CMU DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING +.\" ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL +.\" CMU BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR +.\" ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, +.\" WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, +.\" ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS +.\" SOFTWARE. +.\" ******************************************************************/ +.\" Portions of this file are copyrighted by: +.\" Copyright Copyright 2003 Sun Microsystems, Inc. All rights reserved. +.\" Use is subject to license terms specified in the COPYING file +.\" distributed with the Net-SNMP package. +.\" ******************************************************************/ +.TH SNMPCMD 1 "20 Jul 2010" VVERSIONINFO "Net-SNMP" +.SH NAME +snmpcmd - options and behaviour common to most of the Net-SNMP command-line tools +.SH SYNOPSIS +.B snmpcmd +[OPTIONS] AGENT [PARAMETERS] +.SH DESCRIPTION +This manual page describes the common options for the SNMP commands: +.BR snmpbulkget ", " snmpbulkwalk ", " snmpdelta ", " snmpget ", " +.BR snmpgetnext ", " snmpnetstat ", " snmpset ", " snmpstatus ", " +.BR snmptable ", " snmptest ", " snmptrap ", +.BR " snmpdf", " snmpusm ", " snmpwalk ". " +The command line applications use the SNMP protocol to communicate +with an SNMP capable network entity, an agent. Individual +applications typically (but not necessarily) take additional +parameters that are given after the agent specification. These +parameters are documented in the manual pages for each application. +.SH COMMAND-LINE CONFIG OPTIONS +In addition to the options described in this manual page, all of the +tokens described in the \fIsnmp.conf\fR and other .conf manual pages +can be used on the command line of Net-SNMP applications as well by +prefixing them with "\-\-". EG, specifying +\fI\-\-dontLoadHostConfig=true\fR on the command line will turn of +loading of the host specific configuration files. +.PP +The snmp.conf file settings and the double-dash arguments over-ride +the single-dash arguments. So it's important to note that if +single-dash arguments aren't working because you have settings in the +\fIsnmp.conf\fR file that conflict with them then you'll need to use +the longer-form double-dash arguments to successfully trump the +\fIsnmp.conf\fR file settings. +.SH Generic Options +Thes options control how the Net-SNMP commands behave regardless of +what version of SNMP you are using. See further below for options +that control specific versions or sub-modules of the SNMP protocol. +.TP +.B \-d +Dump (in hexadecimal) the raw SNMP packets sent and received. +.TP +.B \-D\fI[TOKEN[,...]] +Turn on debugging output for the given +.IR "TOKEN" "(s)." +Try +.IR ALL +for extremely verbose output. +.TP +.TP +.B \-h, \-\-help +Display a brief usage message and then exit. +.TP +.B \-H +Display a list of configuration file directives understood by the +command and then exit. +.TP +.BI \-I " [brRhu]" +Specifies input parsing options. See +.B INPUT OPTIONS +below. +.TP +.BI \-L " [eEfFoOsS]" +Specifies output logging options. See +.B LOGGING OPTIONS +below. +.TP +.BI \-m " MIBLIST" +Specifies a colon separated list of MIB modules (not files) to load for +this application. This overrides (or augments) the environment variable +MIBS, the \fIsnmp.conf\fR directive \fImibs\fR, and the list of MIBs +hardcoded into the Net-SNMP library. +.IP +If +.I MIBLIST +has a leading '\-' or '+' character, then the MIB modules listed are +loaded in addition to the default list, coming before or after +this list respectively. +Otherwise, the specified MIBs are loaded \fIinstead\fR of this +default list. +.IP +The special keyword +.I ALL +is used to load all MIB modules in the MIB directory search list. +Every file whose name does not begin with "." will be parsed as +if it were a MIB file. +.TP +.BI \-M " DIRLIST" +Specifies a colon separated list of directories to search for MIBs. +This overrides (or augments) the environment variable MIBDIRS, +the \fIsnmp.conf\fR directive \fImibdirs\fR, and the default +directory hardcoded into the Net-SNMP library +(DATADIR/snmp/mibs). +.IP +If +.I DIRLIST +has a leading '\-' or '+' character, then the given directories are +added to the default list, being searched before or after the +directories on this list respectively. +Otherwise, the specified directories are searched \fIinstead\fR +of this default list. + +Note that the directories appearing later in the list have +have precedence over earlier ones. +.\" +.\" XXX - Say a bit more about what precedence means +.\" +To avoid searching any MIB directories, set the MIBDIRS +environment variable to the empty string (""). +.\" +.\" XXX - or \-M "" ?? +.\" + +Note that MIBs specified using the \-m option or the \fImibs\fR +configuration directive will be loaded from one of the directories +listed by the \-M option (or equivalents). +The \fImibfile\fR directive takes a full path to the specified MIB +file, so this does not need to be in the MIB directory search list. +.TP +.B \-v \fI1\fR | \fI2c\fR | \fI3 +Specifies the protocol version to use: 1 (RFCs 1155-1157), 2c (RFCs 1901-1908), +or 3 (RFCs 2571-2574). The default is typically version 3. +Overrides the \fIdefVersion\fR token in the +.I snmp.conf +file. +.BI \-O " [abeEfnqQsStTuUvxX]" +Specifies output printing options. See +.B OUTPUT OPTIONS +below. +.TP +.BI \-P " [cdeRuwW]" +Specifies MIB parsing options. See +.B MIB PARSING OPTIONS +below. +.TP +.BI \-r " retries" +Specifies the number of retries to be used in the requests. The default +is 5. +.TP +.BI \-t " timeout" +Specifies the timeout in seconds between retries. The default is 1. +Floating point numbers can be used to specify fractions of seconds. +.TP +.B \-V, \-\-version +Display version information for the application and then exit. +.TP +.BI \-Y "name"="value" +.TP +.BI \-\- "name"="value" +Allows one to specify any token ("name") supported in the +.I snmp.conf +file and sets its value to "value". Overrides the corresponding token in the +.I snmp.conf +file. See +.I snmp.conf(5) +for the full list of tokens. + + +.SH SNMPv3 Options +The following options are generic to all forms of SNMPv3, regardless +of whether it's the original SNMPv3 with USM or the newer SNMPv3 over +(D)TLS support. + +.TP +.BI \-l " secLevel" +Set the securityLevel used for SNMPv3 messages +(noAuthNoPriv|authNoPriv|authPriv). Appropriate pass phrase(s) must +provided when using any level higher than noAuthNoPriv. +Overrides the \fIdefSecurityLevel\fR token in the +.I snmp.conf +file. +.TP +.BI \-n " contextName" +Set the contextName used for SNMPv3 messages. The default +contextName is the empty string "". Overrides the \fIdefContext\fR token +in the +.I snmp.conf +file. + +.SH SNMPv3 over TLS Options +These options pass transport-specific parameters to the TLS layer. If +you're using SNMP over TLS or DTLS you'll need to pass a combination +of these either through these command line options or through +snmp.conf configuration tokens. +.PP +A note about +.I "<certificate-specifier>s": +Net-SNMP looks for X.509 certificates in each of the normal SNMP +configuration directory search paths under a "tls" subdirectory. IE, +it will look in ~/.snmp/tls and in /usr/local/share/snmp/tls for +certificates. The certificate components (eg, the public and private +halves) are stored in sub-directories underneath this root set of +directories. See the net\-snmp\-cert tool for help in importing, +creating and managing Net-SNMP certificates. +.I "<certificate-specifier>s" +can reference either a fingerprint of the certificate to use (the +net\-snmp\-cert tool can help you figure out the certificates) or the +filename's prefix can be used. For example, if you had a "snmpd.crt" +certificate file then you could simply refer to the certificate via +the "snmpd" specifier. +.TP +.BI "\-T localCert=<certificate-specifier>" +Indicates to the transport which key should be used to initiate (D)TLS +client connections. This would typically be a certificate found using +the certificate fingerprint, the application name (eg snmpd, snmptrapd, perl, python) or +genericized name "snmpapp" if using one of the generic applications +(snmpget, snmpwalk, etc). This can also be set using the +localCert specifier in a snmp.conf configuration file. +.TP +.BI "\-T peerCert=<certificate-specifier>" +If you expect a particular certificate to be presented by the other +side then you can use this specifier to indicate the certificate it +should present. If it fails to present the expected certificate the +client will refuse to open the connection (because doing otherwise +could lead to man-in-the-middle attacks). This can also be set using +the peerCert specifier in a snmp.conf configuration file. +.TP +.BI "\-T trust_cert=<certificate-specifier>" +If you have a trusted CA certificate you wish to anchor trust with, +you can use this flag to load a given certificate as a trust anchor. +A copy of the certificate must exist within the Net-SNMP certificate +storage system or this must point to a complete path name. Also see +the "trustCert" snmp.conf configuration token. +.TP +.BI "\-T their_hostname=<name>" +If the server's presented certificate can be validating using a trust +anchor then their hostname will be checked to ensure their presented +hostname matches one that is expected (you don't want to connect to +goodhost.example.com and accept a certificate presented by +badhost.example.com do you?). This token can specify the exact host +name expected to be presented by the remote side, either in a +subjectAltName field or in the CommonName field of the server's X.509 +certificate. +.SH SNMPv3 with USM Options +These options are specific to using SNMPv3 with the original +User-based Security Model (USM). +.TP +.BI "\-3[MmKk] 0xHEXKEY" +Sets the keys to be used for SNMPv3 transactions. These options allow +you to set the master authentication and encryption keys (\-3m and \-3M +respectively) or set the localized authentication and encryption keys +(\-3k and \-3K respectively). SNMPv3 keys can be either passed in by +hand using these flags, or by the use of keys generated from passwords +using the \-A and \-X flags discussed below. For further details on +SNMPv3 and its usage of keying information, see the Net-SNMP tutorial +web site ( http://www.Net\-SNMP.org/tutorial\-5/commands/ ). +Overrides the defAuthMasterKey (\-3m), defPrivMasterKey (\-3M), +defAuthLocalizedKey (\-3k) or defPrivLocalizedKey (\-3K) tokens, respectively, +in the +.I snmp.conf +file, see +.I snmp.conf(5). +.TP +.BI \-a " authProtocol" +Set the authentication protocol (MD5 or SHA) used for authenticated SNMPv3 +messages. Overrides the \fIdefAuthType\fR token in the +.I snmp.conf +file. +.TP +.BI \-A " authPassword" +Set the authentication pass phrase used for authenticated SNMPv3 +messages. Overrides the \fIdefAuthPassphrase\fR token in the +.I snmp.conf +file. It is insecure to specify pass phrases on the command line, +see +.I snmp.conf(5). +.TP +.BI \-e " engineID" +Set the authoritative (security) engineID used for SNMPv3 REQUEST +messages, given as a hexadecimal string (optionally prefixed by "0x"). +It is typically not necessary to specify this engine ID, as it will +usually be discovered automatically. +.TP +.BI \-E " engineID" +Set the context engineID used for SNMPv3 REQUEST messages scopedPdu, +given as a hexadecimal string. +If not specified, this will default to the authoritative engineID. +.TP +.BI \-u " secName" +Set the securityName used for authenticated SNMPv3 messages. +Overrides the \fIdefSecurityName\fR token in the +.I snmp.conf +file. +.TP +.BI \-x " privProtocol" +Set the privacy protocol (DES or AES) used for encrypted SNMPv3 messages. +Overrides the \fIdefPrivType\fR token in the +.I snmp.conf +file. This option is only valid if the Net-SNMP software was build +to use OpenSSL. +.TP +.BI \-X " privPassword" +Set the privacy pass phrase used for encrypted SNMPv3 messages. +Overrides the \fIdefPrivPassphrase\fR token in the +.I snmp.conf +file. +It is insecure to specify pass phrases on the command line, see +.I snmp.conf(5). +.TP +.BI \-Z " boots,time" +Set the engineBoots and engineTime used for authenticated SNMPv3 +messages. This will initialize the local notion of the agents +boots/time with an authenticated value stored in the LCD. +It is typically not necessary to specify this option, as these values +will usually be discovered automatically. + + +.SH SNMPv1 and SNMPv2c Options +.TP +.BI \-c " community" +Set the community string for SNMPv1/v2c transactions. +Overrides the \fIdefCommunity\fR token in the +.I snmp.conf +file. + +.SH AGENT SPECIFICATION +.PP +The string +.I AGENT +in the +.B SYNOPSIS +above specifies the remote SNMP entity with which to communicate. +This specification takes the form: +.IP +[<transport-specifier>:]<transport-address> +.PP +At its simplest, the +.I AGENT +specification may consist of a hostname, or an IPv4 address in the +standard "dotted quad" notation. In this case, communication will be +attempted using UDP/IPv4 to port 161 of the given host. Otherwise, +the <transport-address> part of the specification is parsed according +to the following table: +.RS 4 +.TP 28 +.BR "<transport-specifier>" +.BR "<transport-address> format" +.IP "udp" 28 +hostname[:port] +.I or +IPv4-address[:port] +.IP "tcp" 28 +hostname[:port] +.I or +IPv4-address[:port] +.IP "unix" 28 +pathname +.IP "ipx" 28 +[network]:node[/port] +.TP 28 +.IR "" "aal5pvc " or " pvc" +[interface.][VPI.]VCI +.IP "udp6 or udpv6 or udpipv6" 28 +hostname[:port] +.I or +IPv6-address:port +.I or + '['IPv6-address']'[:port] +.IP "tcp6 or tcpv6 or tcpipv6" +hostname[:port] +.I or +IPv6-address:port +.I or + '['IPv6-address']'[:port] +.RE +.PP +Note that <transport-specifier> strings are case-insensitive so that, +for example, "tcp" and "TCP" are equivalent. Here are some examples, +along with their interpretation: +.TP 24 +.IR "hostname:161" +perform query using UDP/IPv4 datagrams to +.I hostname +on port +.IR 161 . +The ":161" is redundant here since that is the default SNMP port in +any case. +.TP 24 +.IR "udp:hostname" +identical to the previous specification. The "udp:" is redundant here +since UDP/IPv4 is the default transport. +.TP 24 +.IR "TCP:hostname:1161" +connect to +.I hostname +on port +.I 1161 +using TCP/IPv4 and perform query over that connection. +.IR "udp6:hostname:10161" +perform the query using UDP/IPv6 datagrams to port +.I 10161 +on +.I hostname +(which will be looked up as an AAAA record). +.TP 24 +.IR "UDP6:[fe80::2d0:b7ff:fe21:c6c0]" +perform the query using UDP/IPv6 datagrams to port 161 at address +.IR fe80::2d0:b7ff:fe21:c6c0 . +.TP 24 +.IR "tcpipv6:[::1]:1611" +connect to port 1611 on the local host +.IR "" ( ::1 +in IPv6 parlance) using TCP/IPv6 and perform query over that connection. +.TP 24 +.IR "tls:hostname:10161" +.TP 24 +.IR "dtls:hostname:10161" +Connects using SNMP over DTLS or TLS as documented by the ISMS working +group (RFCs not yet published as of this date). This will require +(and automatically ensures) that the TSM security model is in use. +You'll also need to set up trust paths for the certificates presented +by the server (see above for descriptions of this). +.TP 24 +.IR "ssh:hostname:22" +Connects using SNMP over SSH as documented by the ISMS working group +(RFCs not yet published as of this date). This will require that the +TSM security model is in use (\-\-defSecurityModel=tsm). +.TP 24 +.IR "ipx::00D0B7AAE308" +perform query using IPX datagrams to node number +.I 00D0B7AAE308 +on the default network, and using the default IPX port of 36879 (900F +hexadecimal), as suggested in RFC 1906. +.TP 24 +.IR "ipx:0AE43409:00D0B721C6C0/1161" +perform query using IPX datagrams to port +.I 1161 +on node number +.I 00D0B721C6C0 +on network number +.IR 0AE43409 . +.TP 24 +.IR "unix:/tmp/local\-agent" +connect to the Unix domain socket +.IR /tmp/local\-agent , +and perform the query over that connection. +.TP 24 +.IR "/tmp/local\-agent" +identical to the previous specification, since the Unix domain is the +default transport iff the first character of the <transport-address> +is a '/'. +.TP 24 +.IR "alias:myname" +perform a connection to the +.I myname +alias which needs to be defined in the snmp.conf file using a line +like " +.I "alias myname udp:127.0.0.1:9161" +". Any type of transport definition can be used as the alias expansion +parameter. Aliases are particularly useful for using repeated complex +transport strings. +.TP 24 +.IR "AAL5PVC:100" +perform the query using AAL5 PDUs sent on the permanent virtual +circuit with VPI=0 and VCI=100 (decimal) on the first ATM adapter in the +machine. +.TP 24 +.IR "PVC:1.10.32" +perform the query using AAL5 PDUs sent on the permanent virtual +circuit with VPI=10 (decimal) and VCI=32 (decimal) on the second ATM +adapter in the machine. Note that "PVC" is a synonym for "AAL5PVC". +.PP +Note that not all the transport domains listed above will always be +available; for instance, hosts with no IPv6 support will not be able +to use udp6 transport addresses, and attempts to do so will result in +the error "Unknown host". Likewise, since AAL5 PVC support is only +currently available on Linux, it will fail with the same error on +other platforms. +.SH "MIB PARSING OPTIONS" +The Net-SNMP MIB parser mostly adheres to the Structure of Management +Information (SMI). As that specification has changed through time, and +in recognition of the (ahem) diversity in compliance expressed in MIB +files, additional options provide more flexibility in reading MIB files. +.TP +.B "\-Pc" +Toggles whether ASN.1 comments should extend to the end of the MIB +source line. +Strictly speaking, a second appearance of "\-\-" should terminate the +comment, but this breaks some MIB files. +The default behaviour (to interpret comments correctly) can also +be set with the configuration token \fIcommentToEOL\fR. +.TP +.B "\-Pd" +Disables the loading of MIB object DESCRIPTIONs when parsing MIB files. +This reduces the amount of memory used by the running application. +.TP +.B "\-Pe" +Toggles whether to show errors encountered when parsing MIB files. +These include +references to IMPORTed modules and MIB objects that cannot be +located in the MIB directory search list. +The default behaviour can also be set with the configuration token \fIshowMibErrors\fR. +.TP +.B "\-PR" +If the same MIB object (parent name and sub-identifier) appears multiple +times in the list of MIB definitions loaded, use the last version to be +read in. By default, the first version will be used, and any duplicates +discarded. +This behaviour can also be set with the configuration token \fImibReplaceWithLatest\fR. + +Such ordering is normally only relevant if there are two MIB files with +conflicting object definitions for the same OID (or different revisions +of the same basic MIB object). +.\" .B WARNING: +.\" Setting this option may result in an incorrect hierarchy. +.\" XXX - Why? +.TP +.B "\-Pu" +Toggles whether to allow the underline character in MIB object names +and other symbols. +Strictly speaking, this is not valid SMI syntax, but some vendor MIB +files define such names. +The default behaviour can also be set with the configuration token \fImibAllowUnderline\fR. +.TP +.B "\-Pw" +Show various warning messages in parsing MIB files and building +the overall OID tree. +This can also be set with the configuration directive +\fImibWarningLevel 1\fR +.TP +.B "\-PW" +Show some additional warning messages, mostly relating to parsing +individual MIB objects. +This can also be set with the configuration directive +\fImibWarningLevel 2\fR + +.SH "OUTPUT OPTIONS" +The format of the output from SNMP commands can be controlled using +various parameters of the \fB\-O\fR flag. +The effects of these sub-options can be seen by comparison with +the following default output (unless otherwise specified): +.RS +.nf +\fC$ snmpget \-c public \-v 1 localhost sysUpTime.0 +SNMPv2\-MIB::sysUpTime.0 = Timeticks: (14096763) 1 day, 15:09:27.63\fR +.fi +.RE + +.TP +.B \-Oa +Display string values as ASCII strings (unless there is a +\fCDISPLAY\-HINT\fR defined for the corresponding MIB object). +By default, the library attempts to determine whether the value is +a printable or binary string, and displays it accordingly. + +This option does not affect objects that \fIdo\fR have a Display Hint. +.TP +.B \-Ob +Display table indexes numerically, rather than trying to interpret +the instance subidentifiers as string or OID values: +.RS +.nf +\fC $ snmpgetnext \-c public \-v 1 localhost vacmSecurityModel + SNMP\-VIEW\-BASED\-ACM\-MIB::vacmSecurityModel.0."wes" = xxx + $ snmpgetnext \-c public \-v 1 \fB\-Ob\fP localhost vacmSecurityModel + SNMP\-VIEW\-BASED\-ACM\-MIB::vacmSecurityModel.0.3.119.101.115 = xxx\fR +.fi +.RE +.TP +.B \-Oe +Removes the symbolic labels from enumeration values: +.RS +.nf +\fC $ snmpget \-c public \-v 1 localhost ipForwarding.0 + IP\-MIB::ipForwarding.0 = INTEGER: forwarding(1) +\fC $ snmpget \-c public \-v 1 \fB\-Oe\fP localhost ipForwarding.0 + IP\-MIB::ipForwarding.0 = INTEGER: 1\fR +.fi +.RE +.TP +.B \-OE +Modifies index strings to escape the quote characters: +.RS +.nf +\fC $ snmpgetnext \-c public \-v 1 localhost vacmSecurityModel + SNMP\-VIEW\-BASED\-ACM\-MIB::vacmSecurityModel.0."wes" = xxx + $ snmpgetnext \-c public \-v 1 \fB\-OE\fP localhost vacmSecurityModel + SNMP\-VIEW\-BASED\-ACM\-MIB::vacmSecurityModel.0.\\"wes\\" = xxx\fR +.fi +.RE +.IP +This allows the output to be reused in shell commands. +.TP +.B \-Of +Include the full list of MIB objects when displaying an OID: +.RS +\fC .iso.org.dod.internet.mgmt.mib\-2.system.sysUpTime.0 =\fR +.RS +\fC Timeticks: (14096763) 1 day, 15:09:27.63\fR +.RE +.RE +.TP +.B \-On +Displays the OID numerically: +.br +\fC .1.3.6.1.2.1.1.3.0 = Timeticks: (14096763) 1 day, 15:09:27.63\fR +.TP +.B \-Oq +Removes the equal sign and type information when displaying varbind values: +.br +\fC SNMPv2\-MIB::sysUpTime.0 1:15:09:27.63\fR +.TP +.B \-OQ +Removes the type information when displaying varbind values: +.br +\fC SNMPv2\-MIB::sysUpTime.0 = 1:15:09:27.63\fR +.TP +.B \-Os +Display the MIB object name (plus any instance or other subidentifiers): +.br +\fC sysUpTime.0 = Timeticks: (14096763) 1 day, 15:09:27.63\fR +.TP +.B \-OS +Display the name of the MIB, as well as the object name: +.br +\fC SNMPv2\-MIB::sysUpTime.0 = Timeticks: (14096763) 1 day, 15:09:27.63\fR +.IP +This is the default OID output format. +.TP +.B \-Ot +Display \fCTimeTicks\fR values as raw numbers: +.br +\fC SNMPv2\-MIB::sysUpTime.0 = 14096763\fR +.TP +.B \-OT +If values are printed as Hex strings, +display a printable version as well. +.TP +.B \-Ou +Display the OID in the traditional UCD-style (inherited from the original +CMU code). +That means removing a series of "standard" prefixes from the OID, +and displaying the remaining list of MIB object names +(plus any other subidentifiers): +.br +\fC system.sysUpTime.0 = Timeticks: (14096763) 1 day, 15:09:27.63\fR +.TP +.B \-OU +Do not print the UNITS suffix at the end of the value. +.TP +.B \-Ov +Display the varbind value only, not the OID: +.RS +.nf +\fC $ snmpget \-c public \-v 1 \fB\-Ov\fP localhost ipForwarding.0 + INTEGER: forwarding(1)\fR +.fi +.RE +.TP +.B \-Ox +Display string values as Hex strings (unless there is a +\fCDISPLAY\-HINT\fR defined for the corresponding MIB object). +By default, the library attempts to determine whether the value is +a printable or binary string, and displays it accordingly. + +This option does not affect objects that \fIdo\fR have a Display Hint. +.TP +.B \-OX +Display table indexes in a more "program like" output, imitating +a traditional array-style index format: +.RS +.nf +\fC $ snmpgetnext \-c public \-v 1 localhost ipv6RouteTable + IPv6\-MIB::ipv6RouteIfIndex.63.254.1.0.255.0.0.0.0.0.0.0.0.0.0.0.64.1 = INTEGER: 2 + $ snmpgetnext \-c public \-v 1 \fB\-OX\fP localhost ipv6RouteTable + IPv6\-MIB::ipv6RouteIfIndex[3ffe:100:ff00:0:0:0:0:0][64][1] = INTEGER: 2 +.fi +.RE +.PP +Most of these options can also be configured via configuration tokens. +See the +.I snmp.conf(5) +manual page for details. + +.SH "LOGGING OPTIONS" +The mechanism and destination to use for logging of warning and error +messages can be controlled by passing various parameters to the +.B \-L +flag. +.TP +.B \-Le +Log messages to the standard error stream. +.TP +.B \-Lf FILE +Log messages to the specified file. +.TP +.B \-Lo +Log messages to the standard output stream. +.TP +.B \-Ls FACILITY +Log messages via syslog, using the specified facility +('d' for LOG_DAEMON, 'u' for LOG_USER, +or '0'-'7' for LOG_LOCAL0 through LOG_LOCAL7). +.PP + +There are also "upper case" versions of each of these options, which +allow the corresponding logging mechanism to be restricted to certain +priorities of message. Using standard error logging as an example: +.TP +.B \-LE pri +will log messages of priority 'pri' and above to standard error. +.TP +.B \-LE p1\-p2 +will log messages with priority between 'p1' and 'p2' (inclusive) to +standard error. +.PP +For +.B \-LF +and +.B \-LS +the priority specification comes before the file or facility token. +The priorities recognised are: +.IP +.B 0 +or +.B ! +for LOG_EMERG, +.br +.B 1 +or +.B a +for LOG_ALERT, +.br +.B 2 +or +.B c +for LOG_CRIT, +.br +.B 3 +or +.B e +for LOG_ERR, +.br +.B 4 +or +.B w +for LOG_WARNING, +.br +.B 5 +or +.B n +for LOG_NOTICE, +.br +.B 6 +or +.B i +for LOG_INFO, and +.br +.B 7 +or +.B d +for LOG_DEBUG. +.PP +Normal output is (or will be!) logged at a priority level of +.B LOG_NOTICE + +.SH "INPUT OPTIONS" +The interpretation of input object names and the values to be assigned +can be controlled using various parameters of the \fB\-I\fR flag. +The default behaviour will be described at the end of this section. +.TP +.B \-Ib +specifies that the given name should be regarded as a regular expression, +to match (case-insensitively) against object names in the MIB tree. +The "best" match will be used - calculated as the one that matches the +closest to the beginning of the node name and the highest in the tree. +.\" +.\" XXX - This is not a particularly clear description. +.\" Need to check the code and/or experiment to +.\" discover exactly what Wes means by this! +For example, the MIB object \fCvacmSecurityModel\fR could be matched by +the expression \fCvacmsecuritymodel\fR (full name, but different case), +or \fCvacm.*model\fR (regexp pattern). + +Note that '.' is a special character in regular expression patterns, +so the expression cannot specify instance subidentifiers or more than +one object name. A "best match" expression will only be applied +against single MIB object names. +For example, the expression \fIsys*ontact.0\fR would not match the +instance \fCsysContact.0\fR (although \fIsys*ontact\fR would match +\fCsysContact\fR). +Similarly, specifying a MIB module name will not succeed +(so \fISNMPv2\-MIB::sys.*ontact\fR would not match either). +.TP +.B \-Ih +disables the use of DISPLAY\-HINT information when assigning values. +This would then require providing the raw value: +.br +\fC snmpset ... HOST\-RESOURCES\-MIB::hrSystemDate.0 +.br + x "07 D2 0C 0A 02 04 06 08"\fR +.br +instead of a formatted version: +.br +\fC snmpset ... HOST\-RESOURCES\-MIB::hrSystemDate.0 +.br + = 2002\-12\-10,2:4:6.8\fR +.TP +.B \-Ir +disables checking table indexes and the value to be assigned against the +relevant MIB definitions. This will (hopefully) result in the remote +agent reporting an invalid request, rather than checking (and rejecting) +this before it is sent to the remote agent. + +Local checks are more efficient (and the diagnostics provided also +tend to be more precise), but disabling this behaviour is particularly +useful when testing the remote agent. +.TP +.B \-IR +enables "random access" lookup of MIB names. +Rather than providing a full OID path to the desired MIB object +(or qualifying this object with an explicit MIB module name), +the MIB tree will be searched for the matching object name. +Thus \fC.iso.org.dod.internet.mib\-2.system.sysDescr.0\fR +(or \fCSNMPv2\-MIB::sysDescr.0\fR) can be specified simply +as \fCsysDescr.0\fR. +.RS +.IP "Warning:" +Since MIB object names are not globally unique, this approach +may return a different MIB object depending on which MIB files +have been loaded. +.RE +.IP +The \fIMIB\-MODULE::objectName\fR syntax has +the advantage of uniquely identifying a particular MIB object, +as well as being slightly more efficient (and automatically +loading the necessary MIB file if necessary). +.TP +.B \-Is SUFFIX +adds the specified suffix to each textual OID given on the command line. +This can be used to retrieve multiple objects from the same row of +a table, by specifying a common index value. +.TP +.B \-IS PREFIX +adds the specified prefix to each textual OID given on the command line. +This can be used to specify an explicit MIB module name for all objects +being retrieved (or for incurably lazy typists). +.TP +.B \-Iu +enables the traditional UCD-style approach to interpreting input OIDs. +This assumes that OIDs are rooted at the 'mib\-2' point in the tree +(unless they start with an explicit '.' or include a MIB module name). +So the \fCsysDescr\fR instance above would be referenced as +\fCsystem.sysDescr.0\fR. + +.PP +Object names specified with a leading '.' are always interpreted as +"fully qualified" OIDs, listing the sequence of MIB objects from the +root of the MIB tree. Such objects and those qualified by an explicit +MIB module name are unaffected by the \fB\-Ib\fR, \fB\-IR\fR and \fB\-Iu\fR flags. + +Otherwise, if none of the above input options are specified, the +default behaviour for a "relative" OID is to try and interpret it +as an (implicitly) fully qualified OID, +then apply "random access" lookup (\fB\-IR\fR), +followed by "best match" pattern matching (\fB\-Ib\fR). + +.SH "ENVIRONMENT VARIABLES" +.IP PREFIX +The standard prefix for object identifiers (when using UCD-style output). +Defaults to .iso.org.dod.internet.mgmt.mib\-2 +.IP MIBS +The list of MIBs to load. Defaults to +SNMPv2\-TC:SNMPv2\-MIB:IF\-MIB:IP\-MIB:TCP\-MIB:UDP\-MIB:SNMP\-VACM\-MIB. +Overridden by the +.B \-m +option. +.IP MIBDIRS +The list of directories to search for MIBs. Defaults to DATADIR/snmp/mibs. +Overridden by the +.B \-M +option. + +.SH FILES +.IP SYSCONFDIR/snmp/snmpd.conf +Agent configuration file. See +.IR snmpd.conf(5) . +.IP SYSCONFDIR/snmp/snmp.conf +.IP ~/.snmp/snmp.conf +Application configuration files. See +.IR snmp.conf(5) . + +.SH "SEE ALSO" +snmpget(1), snmpgetnext(1), snmpset(1), +snmpbulkget(1), snmpbulkwalk(1), snmpwalk(1), +snmptable(1), snmpnetstat(1), snmpdelta(1), snmptrap(1), snmpinform(1), +snmpusm(1), snmpstatus(1), snmptest(1), +snmp.conf(5). + diff --git a/man/snmpconf.1.def b/man/snmpconf.1.def new file mode 100644 index 0000000..cd0c104 --- /dev/null +++ b/man/snmpconf.1.def @@ -0,0 +1,130 @@ +.TH SNMPCONF 1 "25 Feb 2003" VVERSIONINFO "Net-SNMP" +.SH NAME +snmpconf - creates and modifies SNMP configuration files +.SH SYNOPSIS +.B snmpconf +[OPTIONS] [fileToCreate] +.IP "Start with:" +.B snmpconf +\-g basic_setup +.IP "Or even just:" +.B snmpconf +.SH DESCRIPTION +.B snmpconf +is a simple Perl script that walks you through setting up a +configuration file step by step. It should be fairly straight forward +to use. Merely run it and answer its questions. +.PP +In its default mode of operation, it prompts the user with menus +showing sections of the various configuration files it knows about. +When the user selects a section, a sub-menu is shown listing of the +descriptions of the tokens that can be created in that section. When +a description is selected, the user is prompted with questions that +construct the configuration line in question. +.PP +Finally, when the user quits the program any configuration files that +have been edited by the user are saved to the local directory, fully +commented. +.PP +A particularly useful option is the +.B \-g +switch, which walks a user through a specific set of configuration +questions. Run: +.RS +.PP +snmpconf \-g basic_setup +.RE +.PP +for an example. +.SH "OPTIONS" +.TP 8 +.B \-f +Force overwriting existing files in the current directory without +prompting the user if this is a desired thing to do. +.TP +.B \-i +When finished, install the files into the location where the global +system commands expect to find them. +.TP +.B \-p +When finished, install the files into the users home directory's .snmp +subdirectory (where the applications will also search for +configuration files). +.TP +.BI \-I " DIRECTORY" +When finished, install the files into the directory +.IR DIRECTORY . +.TP +.B \-a +Don't ask any questions. Simply read in the various known +configuration files and write them back out again. This has the +effect of "auto-commenting" the configuration files for you. See +the +.B NEAT TRICKS +section below. +.TP +.BI \-r all|none +Read in either all or none of the found configuration files. Normally +.B snmpconf +prompts you for which files you wish to read in. Reading in +these configuration files will merge these files with the results of +the questions that it asks of you. +.TP +.BI \-R " FILE,..." +Read in a specific list of configuration files. +.TP +.BI \-g " GROUPNAME" +Groups of configuration entries can be created that can be used to +walk a user through a series of questions to create an initial +configuration file. There are no menus to navigate, just a list of +questions. Run: +.RS +.RS +.PP +snmpconf \-g basic_setup +.RE +.PP +for a good example. +.RE +.TP +.B \-G +List all the known groups. +.TP +.BI \-c " CONFIGDIR" +.B snmpconf +uses a directory of configuration information to learn about +the files and questions that it should be asking. This option tells +.B snmpconf +to use a different location for configuring itself. +.TP +.B \-q +Run slightly more quietly. Since this is an interactive program, I +don't recommend this option since it only removes information from the +output that is designed to help you. +.TP +.B \-d +Turn on +.B lots +of debugging output. +.TP +.B \-D +Add +.B even more +debugging output in the form of Perl variable dumps. +.IP +.SH "NEAT TRICKS" +.IP "snmpconf \-g basic_setup" +Have I mentioned this command enough yet? It's designed to walk +someone through an initial setup for the +.I snmpd(8) +daemon. Really, you should try it. +.IP "snmpconf \-R /usr/local/snmp/snmpd.conf \-a \-f snmpd.conf" +Automatically reads in an snmpd.conf file (for example) and adds +comments to them describing what each token does. Try it. It's cool. +.SH "NOTES" +.B snmpconf +is actually a very generic utility that could be easily +configured to help construct just about any kind of configuration +file. Its default configuration set of files are SNMP based. +.SH SEE ALSO +snmpd(8), snmp_config(5), snmp.conf(5), snmpd.conf(5) diff --git a/man/snmpd.8.def b/man/snmpd.8.def new file mode 100644 index 0000000..f173396 --- /dev/null +++ b/man/snmpd.8.def @@ -0,0 +1,355 @@ +.TH SNMPD 8 "30 Jun 2010" VVERSIONINFO "Net-SNMP" +.SH NAME +snmpd - daemon to respond to SNMP request packets. +.SH SYNOPSIS +.B snmpd +[OPTIONS] [LISTENING ADDRESSES] +.SH DESCRIPTION +.B snmpd +is an SNMP agent which binds to a port and awaits requests from +SNMP management software. Upon receiving a request, it processes the +request(s), collects the requested information and/or performs the +requested operation(s) and returns the information to the sender. +.SH OPTIONS +.TP 8 +.B \-a +Log the source addresses of incoming requests. +.TP +.B \-A +Append to the log file rather than truncating it. +.TP +.B "\-c" \fIFILE +Read +.I FILE +as a configuration file +(or a comma-separated list of configuration files). Note that the loaded +file will only understand snmpd.conf tokens, unless the configuration type +is specified in the file as described in the snmp_config man page under +SWITCHING CONFIGURATION TYPES IN MID-FILE. +.TP +.B \-C +Do not read any configuration files except the ones optionally specified by the +.B \-c +option. +Note that this behaviour also covers the persistent configuration files. +This may result in dynamically-assigned values being reset following an +agent restart, unless the relevant persistent config files are +explicitly loaded using the +.B \-c +option. +.TP +.B \-d +Dump (in hexadecimal) the sent and received SNMP packets. +.TP +.B \-D\fI[TOKEN[,...]] +Turn on debugging output for the given +.IR "TOKEN" "(s)." +Without any tokens specified, it defaults to printing all the tokens +(which is equivalent to the keyword "ALL"). +You might want to try +.IR ALL +for extremely verbose output. Note: You can not put a space between +the \-D flag and the listed TOKENs. +.TP +.B \-f +Do not fork() from the calling shell. +.TP +.B \-g \fIGID +Change to the numerical group ID +.I GID +after opening listening sockets. +.TP +.B \-h, \-\-help +Display a brief usage message and then exit. +.TP +.B \-H +Display a list of configuration file directives understood by the +agent and then exit. +.TP +.B \-I \fI[\-]INITLIST +Specifies which modules should (or should not) be initialized +when the agent starts up. If the comma-separated +.I INITLIST +is preceded +with a '\-', it is the list of modules that should \fInot\fR be started. +Otherwise this is the list of the \fIonly\fR modules that should be started. + +To get a list of compiled modules, run the agent with the arguments +.I "\-Dmib_init \-H" +(assuming debugging support has been compiled in). +.TP +.B \-L[efos] +Specify where logging output should be directed (standard error or output, +to a file or via syslog). See LOGGING OPTIONS in snmpcmd(5) for details. +.TP +.BR \-m " \fIMIBLIST" +Specifies a colon separated list of MIB modules to load for this +application. This overrides the environment variable MIBS. +See \fIsnmpcmd(1)\fR for details. +.TP +.BR \-M " \fIDIRLIST" +Specifies a colon separated list of directories to search for MIBs. +This overrides the environment variable MIBDIRS. +See \fIsnmpcmd(1)\fR for details. +.TP +.B \-n \fINAME +Set an alternative application name (which will affect the +configuration files loaded). +By default this will be \fIsnmpd\fR, regardless of the name +of the actual binary. +.TP +.B \-p \fIFILE +Save the process ID of the daemon in +.IR FILE "." +.TP +.B \-q +Print simpler output for easier automated parsing. +.TP +.B \-r +Do not require root access to run the daemon. Specifically, do not exit +if files only accessible to root (such as /dev/kmem etc.) cannot be +opened. +.TP +.B \-u \fIUID +Change to the user ID +.I UID +(which can be given in numerical or textual form) after opening +listening sockets. +.TP +.B \-U +Instructs the agent to not remove its pid file (see the +.B \-p +option) on shutdown. Overrides the leave_pidfile token in the +.I snmpd.conf +file, see +.I snmpd.conf(5). +.TP +.B \-v, \-\-version +Print version information for the agent and then exit. +.TP +.B \-V +Symbolically dump SNMP transactions. +.TP +.B \-x \fIADDRESS +Listens for AgentX connections on the specified address +rather than the default AGENTX_SOCKET. +The address can either be a Unix domain socket path, +or the address of a network interface. The format is the same as the +format of listening addresses described below. +.TP +.B \-X +Run as an AgentX subagent rather than as an SNMP master agent. +.TP +.BI \-\- "name"="value" +Allows one to specify any token ("name") supported in the +.I snmpd.conf +file and sets its value to "value". Overrides the corresponding token in the +.I snmpd.conf +file. See +.I snmpd.conf(5) +for the full list of tokens. +.SH LISTENING ADDRESSES +By default, +.B snmpd +listens for incoming SNMP requests on UDP port 161 on all IPv4 interfaces. +However, it is possible to modify this behaviour by specifying one or more +listening addresses as arguments to \fBsnmpd\fR. +A listening address takes the form: +.IP +[<transport-specifier>:]<transport-address> +.PP +At its simplest, a listening address may consist only of a port +number, in which case +.B snmpd +listens on that UDP port on all IPv4 interfaces. Otherwise, the +<transport-address> part of the specification is parsed according to +the following table: +.RS 4 +.TP 28 +.BR "<transport-specifier>" +.BR "<transport-address> format" +.IP "udp \fI(default)\fR" 28 +hostname[:port] +.I or +IPv4-address[:port] +.IP "tcp" 28 +hostname[:port] +.I or +IPv4-address[:port] +.IP "unix" 28 +pathname +.IP "ipx" 28 +[network]:node[/port] +.TP 28 +.IR "" "aal5pvc " or " pvc" +[interface.][VPI.]VCI +.TP 28 +.IR "" "udp6 " or " udpv6 " or " udpipv6" +hostname[:port] +.I or +IPv6-address[:port] +.TP 28 +.IR "" "tcp6 " or " tcpv6 " or " tcpipv6" +hostname[:port] +.I or +IPv6-address[:port] +.TP 28 +.IR "" "ssh" +hostname:port +.TP 28 +.IR "" "dtlsudp" +hostname:port +.RE +.PP +Note that <transport-specifier> strings are case-insensitive so that, +for example, "tcp" and "TCP" are equivalent. Here are some examples, +along with their interpretation: +.TP 24 +.IR "127.0.0.1:161" +listen on UDP port 161, but only on the loopback interface. This +prevents +.B snmpd +being queried remotely. The port specification ":161" is +not strictly necessary since that is the default SNMP port. +.TP 24 +.IR "TCP:1161" +listen on TCP port 1161 on all IPv4 interfaces. +.TP 24 +.IR "ipx:/40000" +listen on IPX port 40000 on all IPX interfaces. +.TP 24 +.IR "unix:/tmp/local\-agent" +listen on the Unix domain socket \fI/tmp/local\-agent\fR. +.TP 24 +.IR "/tmp/local\-agent" +is identical to the previous specification, since the Unix domain is +assumed if the first character of the <transport-address> is '/'. +.TP 24 +.IR "PVC:161" +listen on the AAL5 permanent virtual circuit with VPI=0 and VCI=161 +(decimal) on the first ATM adapter in the machine. +.TP 24 +.IR "udp6:10161" +listen on port 10161 on all IPv6 interfaces. +.TP 24 +.IR "ssh:127.0.0.1:22" +Allows connections from the snmp subsystem on the ssh server on port +22. The details of using SNMP over SSH are defined below. +.TP 24 +.IR "dtlsudp:127.0.0.1:9161" +Listen for connections over DTLS on UDP port 9161. The snmp.conf file +must have the +.IR serverCert, +configuration tokens defined. +.PP +Note that not all the transport domains listed above will always be +available; for instance, hosts with no IPv6 support will not be able +to use udp6 transport addresses, and attempts to do so will result in +the error "Error opening specified endpoint". Likewise, since AAL5 +PVC support is only currently available on Linux, it will fail with +the same error on other platforms. +.SH Transport Specific Notes +.RS 0 +.TP 8 +ssh +The SSH transport, on the server side, is actually just a unix +named pipe that can be connected to via a ssh subsystem configured in +the main ssh server. The pipe location (configurable with the +sshtosnmpsocket token in snmp.conf) is +.I /var/net\-snmp/sshtosnmp. +Packets should be submitted to it via the sshtosnmp application, which +also sends the user ID as well when starting the connection. The TSM +security model should be used when packets should process it. +.IP +The +.I sshtosnmp +command knows how to connect to this pipe and talk to +it. It should be configured in the +.IR "OpenSSH sshd" +configuration file (which is normally +.IR "/etc/ssh/sshd_config" +using the following configuration line: +.TP 8 +.IP +Subsystem snmp /usr/local/bin/sshtosnmp +.IP +The +.I sshtosnmp +command will need read/write access to the +.I /var/net\-snmp/sshtosnmp +pipe. Although it should be fairly safe to grant access to the +average user since it still requires modifications to the ACM settings +before the user can perform operations, paranoid administrators may +want to make the /var/net\-snmp directory accessible only by users in a +particular group. Use the +.I sshtosnmpsocketperms +snmp.conf configure option to set the permissions, owner and group of +the created socket. +.IP +Access control can be granted to the user "foo" using the following +style of simple snmpd.conf settings: +.TP 8 +.IP +rouser \-s tsm foo authpriv +.IP +Note that "authpriv" is acceptable assuming as SSH protects everything +that way (assuming you have a non-insane setup). +snmpd has no notion of how SSH has actually protected a packet and +thus the snmp agent assumes all packets passed through the SSH +transport have been protected at the authpriv level. +.TP 8 +dtlsudp +The DTLS protocol, which is based off of TLS, requires both client and +server certificates to establish the connection and authenticate both +sides. In order to do this, the client will need to configure the +snmp.conf file +with the +.IR clientCert +configuration tokens. The server will need to configure the snmp.conf +file with the +.IR serverCert +configuration tokens defined. +.IP +Access control setup is similar to the ssh transport as the TSM +security model should be used to protect the packet. +.RE +.SH CONFIGURATION FILES +.PP +.B snmpd +checks for the existence of and parses the following files: +.TP 6 +.B SYSCONFDIR/snmp/snmp.conf +Common configuration for the agent and applications. See +.I snmp.conf(5) +for details. +.TP +.B SYSCONFDIR/snmp/snmpd.conf +.TP +.B SYSCONFDIR/snmp/snmpd.local.conf +Agent-specific configuration. See +.I snmpd.conf(5) +for details. These files are optional and may be used to configure +access control, trap generation, subagent protocols and much else +besides. +.IP +In addition to these two configuration files in SYSCONFDIR/snmp, the +agent will read any files with the names +.I snmpd.conf +and +.I snmpd.local.conf +in a colon separated path specified in the +SNMPCONFPATH environment variable. +.TP +.B DATADIR/snmp/mibs/ +The agent will also load all files in this directory as MIBs. It will +not, however, load any file that begins with a '.' or descend into +subdirectories. +.SH SEE ALSO +(in recommended reading order) +.PP +snmp_config(5), +snmp.conf(5), +snmpd.conf(5) +.\" Local Variables: +.\" mode: nroff +.\" End: diff --git a/man/snmpd.conf.5.def b/man/snmpd.conf.5.def new file mode 100644 index 0000000..5f85f72 --- /dev/null +++ b/man/snmpd.conf.5.def @@ -0,0 +1,1769 @@ +.TH SNMPD.CONF 5 "30 Jun 2010" VVERSIONINFO "Net-SNMP" +.SH NAME +snmpd.conf - configuration file for the Net-SNMP SNMP agent +.SH DESCRIPTION +The Net-SNMP agent uses one or more configuration files +to control its operation and the management information +provided. +These files (\fBsnmpd.conf\fR and \fBsnmpd.local.conf\fR) +can be located in one of several locations, as described in the +.I snmp_config(5) +manual page. +.PP +The (perl) application +.B snmpconf +can be used to generate configuration files for the +most common agent requirements. See the +.I snmpconf(1) +manual page for more information, or try running the +command: +.RS +.IP "snmpconf \-g basic_setup" +.RE +.PP +There are a large number of directives that can be specified, +but these mostly fall into four distinct categories: +.IP \(bu +those controlling who can access the agent +.IP \(bu +those configuring the information that is supplied by the agent +.IP \(bu +those controlling active monitoring of the local system +.IP \(bu +those concerned with extending the functionality of the agent. +.PP +Some directives don't fall naturally into any of these four +categories, but this covers the majority of the contents of +a typical +.B snmpd.conf +file. +A full list of recognised directives can be obtained by running +the command: +.RS +.IP "snmpd \-H" +.RE +.SH AGENT BEHAVIOUR +Although most configuration directives are concerned with the MIB +information supplied by the agent, there are a handful of directives that +control the behaviour of \fIsnmpd\fR considered simply as a daemon +providing a network service. +.IP "agentaddress [<transport-specifier>:]<transport-address>[,...]" +defines a list of listening addresses, on which to receive incoming +SNMP requests. +See the section +.B LISTENING ADDRESSES +in the +.I snmpd(8) +manual page for more information about the format of listening +addresses. +.IP +The default behaviour is to +listen on UDP port 161 on all IPv4 interfaces. +.IP "agentgroup {GROUP|#GID}" +changes to the specified group after opening the listening port(s). +This may refer to a group by name (GROUP), or a numeric group ID +starting with '#' (#GID). +.IP "agentuser {USER|#UID}" +changes to the specified user after opening the listening port(s). +This may refer to a user by name (USER), or a numeric user ID +starting with '#' (#UID). +.IP "leave_pidfile yes" +instructs the agent to not remove its pid file on shutdown. Equivalent to +specifying "\-U" on the command line. +.IP "maxGetbulkRepeats NUM" +Sets the maximum number of responses allowed for a single variable in +a getbulk request. Set to 0 to enable the default and set it to \-1 to +enable unlimited. Because memory is allocated ahead of time, sitting +this to unlimited is not considered safe if your user population can +not be trusted. A repeat number greater than this will be truncated +to this value. +.IP +This is set by default to -1. +.IP "maxGetbulkResponses NUM" +Sets the maximum number of responses allowed for a getbulk request. +This is set by default to 100. Set to 0 to enable the default and set +it to \-1 to enable unlimited. Because memory is allocated ahead of +time, sitting this to unlimited is not considered safe if your user +population can not be trusted. +.IP +In general, the total number of responses will not be allowed to +exceed the maxGetbulkResponses number and the total number returned +will be an integer multiple of the number of variables requested times +the calculated number of repeats allow to fit below this number. +.IP +Also not that processing of maxGetbulkRepeats is handled first. +.SS SNMPv3 Configuration - Real Security +SNMPv3 is added flexible security models to the SNMP packet structure +so that multiple security solutions could be used. SNMPv3 was +original defined with a "User-based Security Model" (USM) [RFC3414] +that required maintaining a SNMP-specific user database. This was +later determined to be troublesome to maintain and had some minor +security issues. The IETF has since added additional security models +to tunnel SNMP over SSH [RFC5592] and DTLS/TLS [RFC-to-be]. Net-SNMP +contains robust support for SNMPv3/USM, SNMPv3/TLS, and SNMPv3/DTLS. +It contains partial support for SNMPv3/SSH as well but has not been as +extensively tested. It also contains code for support for an +experimental Kerberos based SNMPv3 that never got standardized. +.PP +Hopefully more SNMP software and devices will eventually support SNMP +over (D)TLS or SSH, but it is likely that devices with original +support for SNMP will only contain support for USM users. If your +network manager supports SNMP over (D)TLS or SNMP over SSH we suggest +you use one of these mechanisms instead of using USM, but as always +with Net-SNMP we give you the options to pick from so you can make the +choice that is best for you. +.SS SNMPv3 generic parameters +These parameters are generic to all the forms of SNMPv3. The SNMPv3 +protocol defines "engineIDs" that uniquely identify an agent. The +string must be consistent through time and should not change or +conflict with another agent's engineID. Ever. Internally, Net-SNMP +by default creates a unique engineID that is based off of the current system +time and a random number. This should be sufficient for most users +unless you're embedding our agent in a device where these numbers +won't vary between boxes on the devices initial boot. +.IP +EngineIDs are used both as a "context" for selecting information from +the device and SNMPv3 with USM uses it to create unique entries for +users in its user table. +.IP +The Net-SNMP agent offers the following mechanisms for setting the +engineID, but again you should only use them if you know what you're doing: +.IP "engineID STRING" +specifies that the engineID should be built from the given text STRING. +.IP "engineIDType 1|2|3" +specifies that the engineID should be built from the IPv4 address (1), +IPv6 address (2) or MAC address (3). Note that changing the IP address +(or switching the network interface card) may cause problems. +.IP "engineIDNic INTERFACE" +defines which interface to use when determining the MAC address. +If \fIengineIDType 3\fR is not specified, then this directive +has no effect. +.IP +The default is to use eth0. +.\" +.\" What if this doesn't exist ? +.\" +.SS SNMPv3 over TLS +SNMPv3 may be tunneled over TLS and DTLS. TLS runs over TCP and DTLS +is the UDP equivalent. Wes Hardaker (the founder of Net-SNMP) +performed a study and presented it at an IETF meeting that showed that +TCP based protocols are sufficient for stable networks but quickly +becomes a problem in unstable networks with even moderate levels of +packet loss (~ 20-30%). If you are going to use TLS or DTLS, you +should use the one appropriate for your networking environment. You +should potentially turn them both on so your management system can +access either the UDP or the TCP port as needed. +.PP +Many of the configuration tokens described below are prefixed with +a '[snmp]' tag. If you place these tokens in your snmpd.conf file, +this take is required. See the snmp_config(5) manual page for the +meaning of this context switch. +.IP "[snmp] localCert <specifier>" +This token defines the default X.509 public key to use as the server's +identity. It should either be a fingerprint or a filename. To create +a public key for use, please run the "net\-snmp\-cert" utility which +will help you create the required certificate. +.IP +The default value for this is the certificate in the "snmpd" named +certificate file. +.IP "[snmp] tlsAlgorithms <algorithms>" +This string will select the algorithms to use when negotiating +security during (D)TLS session establishment. See the openssl manual +page ciphers(1) for details on the format. Examples strings include: +.RS +.nf + +DEFAULT +ALL +HIGH +HIGH:!AES128\-SHA +.fi +.RE +.IP +The default value is whatever openssl itself was configured with. +.IP "[snmp] x059CRLFile" +If you are using a Certificate Authority (CA) that publishes a +Certificate Revocation List (CRL) then this token can be used to +specify the location in the filesystem of a copy of the CRL file. +Note that Net-SNMP will not pull a CRL over http and this must be a +file, not a URL. Additionally, OpenSSL does not reload a CRL file +when it has changed so modifications or updates to the file will only +be noticed upon a restart of the snmpd agent. + +.IP "certSecName PRIORITY FINGERPRINT OPTIONS" +OPTIONS can be one of <\-\-sn SECNAME | \-\-rfc822 | \-\-dns | \-\-ip | \-\-cn | \-\-any>. +.IP +The certSecName token will specify how to map a certificate field from +the client's X.509 certificate to a SNMPv3 username. Use the \-\-sn +SECNAME flag to directly specify a securityName for a given +certificate. The other flags extract a particular component of the +certificate for use as a snmpv3 securityName. These fields are one +of: A SubjectAltName containing an rfc822 value (eg hardaker@net\-snmp.org), +A SubjectAltName containing a dns name value (eg foo.net\-snmp.org), +an IP address (eg 192.0.2.1) or a common name "Wes Hardaker". The +\-\-any flag specifies that any of the subjecAltName fields may be +used. Make sure once a securityName has been selected that it is +given authorization via the VACM controls discussed later in this +manual page. +.IP +See the http://www.net\-snmp.org/wiki/index.php/Using_DTLS web page for +more detailed instructions for setting up (D)TLS. +.IP "trustCert <specifier>" +For X509 to properly verify a certificate, it should be verifiable up +until a trust anchor for it. This trust anchor is typically a CA +certificate but it could also be a self-signed certificate. The +"trustCert" token should be used to load specific trust anchors into the +verification engine. +.PP +SNMP over (D)TLS requires the use of the Transport Security Model +(TSM), so read the section on the usage of the Transport Security +Model as well. Make sure when you configure the VACM to accept +connections from (D)TLS that you use the "tsm" security model. E.G.: +.fi + +rwuser \-s tsm hardaker@net\-snmp.org +.fi +.SS SNMPv3 over SSH Support +To use SSH, you'll need to configure sshd to invoke the sshtosnmp +program as well as configure the access control settings to allow +access through the tsm security model using the user name provided to +snmpd by the ssh transport. +.SS SNMPv3 with the Transport Security Model (TSM) +The Transport Security Model [RFC5591] defines a SNMPv3 security +system for use with "tunneled" security protocols like TLS, DTLS and +SSH. It is a very simple security model that simply lets properly +protected packets to pass through into the snmp application. The +transport is required to pass a securityName to use to the TSM and the +TSM may optionally prefix this with a transport string (see below). +.IP "tsmUseTransportPrefix (1|yes|true|0|no|false)" +If set to true, the TSM module will take every securityName passed to +it from the transports underneath and prefix it with a string that +specifically identities the transport it came from. This is useful to +avoid securityName clashes with transports that generate identical +security names. For example, if the ssh security transport delivered +the security name of "hardaker" for a SSH connection and the TLS +security transport also delivered the security name of "hardaker" for +a TLS connection then it would be impossible to separate out these two +users to provide separate access control rights. With the +tsmUseTransportPrefix set to true, however, the securityNames would be +prefixed appropriately with one of: "tls:", "dtls:" or "ssh:". +.SS SNMPv3 with the User-based Security Model (USM) +SNMPv3 was originally defined using the User-Based Security Model +(USM), which contains a private list of users and keys specific to the +SNMPv3 protocol. The operational community, however, declared it a +pain to manipulate yet another database and would prefer to use +existing infrastructure. To that end the IETF created the ISMS +working group to battle that problem, and the ISMS working group +decided to tunnel SNMP over SSH and DTLS to make use existing user and +authentication infrastructures. +.SS SNMPv3 USM Users +To use the USM based SNMPv3-specific users, you'll need to create +them. It is recommended you +.B "use the net\-snmp\-config command" +to do this, but you can also do it by directly specifying createUser +directives yourself instead: +.IP "createUser [\-e ENGINEID] username (MD5|SHA) authpassphrase [DES|AES] [privpassphrase]" +.IP +MD5 and SHA are the authentication types to use. DES and AES are the +privacy protocols to use. If the privacy +passphrase is not specified, it is assumed to be the same as the +authentication passphrase. Note that the users created will be +useless unless they are also added to the VACM access control tables +described above. +.IP +SHA authentication and DES/AES privacy require OpenSSL to be installed and +the agent to be built with OpenSSL support. MD5 authentication may be +used without OpenSSL. +.IP +Warning: the minimum pass phrase length is 8 characters. +.IP +SNMPv3 users can be created at runtime using the +.I snmpusm(1) +command. +.IP +Instead of figuring out how to use this directive and where to put it +(see below), just run "net\-snmp\-config \-\-create\-snmpv3\-user" instead, +which will add one of these lines to the right place. +.IP +This directive should be placed into the +PERSISTENT_DIRECTORY/snmpd.conf file instead of the other normal +locations. The reason is that the information is read from the file +and then the line is removed (eliminating the storage of the master +password for that user) and replaced with the key that is derived from +it. This key is a localized key, so that if it is stolen it can not +be used to access other agents. If the password is stolen, however, +it can be. +.IP +If you need to localize the user to a particular EngineID (this is +useful mostly in the similar snmptrapd.conf file), you can use the \-e +argument to specify an EngineID as a hex value (EG, "0x01020304"). +.IP +If you want to generate either your master or localized keys directly, +replace the given password with a hexstring (preceded by a "0x") and +precede the hex string by a \-m or \-l token (respectively). EGs: +.IP +.RS +.nf +[these keys are *not* secure but are easy to visually parse for +counting purposes. Please generate random keys instead of using +these examples] + +createUser myuser SHA \-l 0x0001020304050607080900010203040506070809 AES \-l 0x00010203040506070809000102030405 +createUser myuser SHA \-m 0x0001020304050607080900010203040506070809 AES \-m 0x0001020304050607080900010203040506070809 +.fi +.RE +.IP +Due to the way localization happens, localized privacy keys are +expected to be the length needed by the algorithm (128 bits for all +supported algorithms). Master encryption keys, though, need to be the +length required by the authentication algorithm not the length +required by the encrypting algorithm (MD5: 16 bytes, SHA: 20 bytes). +.SH ACCESS CONTROL +.B snmpd +supports the View-Based Access Control Model (VACM) as defined in RFC +2575, to control who can retrieve or update information. To this end, +it recognizes various directives relating to access control. +.SS Traditional Access Control +Most simple access control requirements can be specified using the +directives \fIrouser\fR/\fIrwuser\fR (for SNMPv3) or +\fIrocommunity\fR/\fIrwcommunity\fR (for SNMPv1 or SNMPv2c). +.IP "rouser [\-s SECMODEL] USER [noauth|auth|priv [OID | \-V VIEW [CONTEXT]]]" +.IP "rwuser [\-s SECMODEL] USER [noauth|auth|priv [OID | \-V VIEW [CONTEXT]]]" +specify an SNMPv3 user that will be allowed read-only (GET and GETNEXT) +or read-write (GET, GETNEXT and SET) access respectively. +By default, this will provide access to the full OID tree for authenticated +(including encrypted) SNMPv3 requests, using the default context. +An alternative minimum security level can be specified using \fInoauth\fR +(to allow unauthenticated requests), or \fIpriv\fR (to enforce use of +encryption). The OID field restricts access for that +user to the subtree rooted at the given OID, or the named view. +An optional context can also be specified, or "context*" to denote a context +prefix. If no context field is specified (or the token "*" is used), the +directive will match all possible contexts. +.IP +If SECMODEL is specified then it will be the security model required +for that user (note that identical user names may come in over +different security models and will be appropriately separated via the +access control settings). The default security model is "usm" and the +other common security models are likely "tsm" when using (D)TLS or SSH +support and "ksm" if the Kerberos support has been compiled in. +.IP "rocommunity COMMUNITY [SOURCE [OID | \-V VIEW [CONTEXT]]]" +.IP "rwcommunity COMMUNITY [SOURCE [OID | \-V VIEW [CONTEXT]]]" +specify an SNMPv1 or SNMPv2c community that will be allowed read-only +(GET and GETNEXT) or read-write (GET, GETNEXT and SET) access respectively. +By default, this will provide access to the full OID tree for such requests, +regardless of where they were sent from. The SOURCE token can be used to +restrict access to requests from the specified system(s) - see +\fIcom2sec\fR for the full details. The OID field restricts access for +that community to the subtree rooted at the given OID, or named view. +Contexts are typically less relevant to community-based SNMP versions, +but the same behaviour applies here. +.IP "rocommunity6 COMMUNITY [SOURCE [OID | \-V VIEW [CONTEXT]]]" +.IP "rwcommunity6 COMMUNITY [SOURCE [OID | \-V VIEW [CONTEXT]]]" +are directives relating to requests received using IPv6 +(if the agent supports such transport domains). +The interpretation of the SOURCE, OID, VIEW and CONTEXT tokens are exactly +the same as for the IPv4 versions. +.PP +In each case, only one directive should be specified for a given SNMPv3 user, +or community string. +It is \fBnot\fR appropriate to specify both \fIrouser\fR +and \fIrwuser\fR directives referring to the same SNMPv3 user (or equivalent +community settings). The \fIrwuser\fR directive provides all the access +of \fIrouser\fR (as well as allowing SET support). +The same holds true for the community-based directives. +.PP +More complex access requirements (such as access to two +or more distinct OID subtrees, or different views for GET and SET requests) +should use one of the other access control mechanisms. +Note that if several distinct communities or SNMPv3 users need to be granted +the same level of access, it would also be more efficient to use the main VACM +configuration directives. +.SS VACM Configuration +The full flexibility of the VACM is available using four configuration +directives \- \fIcom2sec\fR, \fIgroup\fR, \fIview\fR and \fIaccess\fR. +These provide direct configuration of the underlying VACM tables. +.IP "com2sec [\-Cn CONTEXT] SECNAME SOURCE COMMUNITY" +.IP "com2sec6 [\-Cn CONTEXT] SECNAME SOURCE COMMUNITY" +map an SNMPv1 or SNMPv2c community string to a security name - either from +a particular range of source addresses, or globally (\fI"default"\fR). +A restricted source can either be a specific hostname (or address), or +a subnet - represented as IP/MASK (e.g. 10.10.10.0/255.255.255.0), or +IP/BITS (e.g. 10.10.10.0/24), or the IPv6 equivalents. +.IP +The same community string can be specified in several separate directives +(presumably with different source tokens), and the first source/community +combination that matches the incoming request will be selected. +Various source/community combinations can also map to the same security name. +.IP +If a CONTEXT is specified (using \fI\-Cn\fR), the community string will be +mapped to a security name in the named SNMPv3 context. Otherwise the +default context ("") will be used. +.IP "com2secunix [\-Cn CONTEXT] SECNAME SOCKPATH COMMUNITY" +is the Unix domain sockets version of \fIcom2sec\fR. +.IP "group GROUP {v1|v2c|usm|tsm|ksm} SECNAME" +maps a security name (in the specified security model) into +a named group. Several \fIgroup\fR directives can specify the +same group name, allowing a single access setting to apply to several +users and/or community strings. +.IP +Note that groups must be set up for the two community-based models separately - +a single \fIcom2sec\fR (or equivalent) directive will typically be +accompanied by \fBtwo\fR \fIgroup\fR directives. +.IP "view VNAME TYPE OID [MASK]" +defines a named "view" - a subset of the overall OID tree. This is most +commonly a single subtree, but several \fIview\fR directives can be given +with the same view name (VNAME), to build up a more complex collection of OIDs. +TYPE is either \fIincluded\fR or \fIexcluded\fR, which can again define +a more complex view (e.g by excluding certain sensitive objects +from an otherwise accessible subtree). +.IP +MASK is a list of hex octets (optionally separated by '.' or ':') with +the set bits indicating which subidentifiers in the view OID to match +against. If not specified, this defaults to matching the OID exactly +(all bits set), thus defining a simple OID subtree. So: +.RS +.RS +view iso1 included .iso 0xf0 +.br +view iso2 included .iso +.br +view iso3 included .iso.org.dod.mgmt 0xf0 +.RE +.RE +.IP +would all define the same view, covering the whole of the 'iso(1)' subtree +(with the third example ignoring the subidentifiers not covered by the mask). +.IP +More usefully, the mask can be used to define a view covering a particular +row (or rows) in a table, by matching against the appropriate table index +value, but skipping the column subidentifier: +.RS +.RS +.IP "view ifRow4 included .1.3.6.1.2.1.2.2.1.0.4 0xff:a0" +.RE +.RE +.IP +Note that a mask longer than 8 bits must use ':' to separate the individual +octets. +.IP "access GROUP CONTEXT {any|v1|v2c|usm|tsm|ksm} LEVEL PREFX READ WRITE NOTIFY" +maps from a group of users/communities (with a particular security model +and minimum security level, and in a specific context) to one of three views, +depending on the request being processed. +.IP +LEVEL is one of \fInoauth\fR, \fIauth\fR, or \fIpriv\fR. +PREFX specifies how CONTEXT should be matched against the context of +the incoming request, either \fIexact\fR or \fIprefix\fR. +READ, WRITE and NOTIFY specifies the view to be used for GET*, SET +and TRAP/INFORM requests (althought the NOTIFY view is not currently used). +For v1 or v2c access, LEVEL will need to be \fInoauth\fR. +.SS Typed-View Configuration +The final group of directives extend the VACM approach into a more flexible +mechanism, which can be applied to other access control requirements. Rather than +the fixed three views of the standard VACM mechanism, this can be used to +configure various different view types. As far as the main SNMP agent is +concerned, the two main view types are \fIread\fR and \fIwrite\fR, +corresponding to the READ and WRITE views of the main \fIaccess\fR directive. +See the 'snmptrapd.conf(5)' man page for discussion of other view types. +.IP "authcommunity TYPES COMMUNITY [SOURCE [OID | \-V VIEW [CONTEXT]]]" +is an alternative to the \fIrocommunity\fR/\fIrwcommunity\fR directives. +TYPES will usually be \fIread\fR or \fIread,write\fR respectively. +The view specification can either be an OID subtree (as before), +or a named view (defined using the +\fIview\fR directive) for greater flexibility. If this is omitted, +then access will be allowed to the full OID tree. +If CONTEXT is specified, access is configured within this SNMPv3 context. +Otherwise the default context ("") is used. +.IP "authuser TYPES [\-s MODEL] USER [LEVEL [OID | \-V VIEW [CONTEXT]]]" +is an alternative to the \fIrouser\fR/\fIrwuser\fR directives. +The fields TYPES, OID, VIEW and CONTEXT have the same meaning as for +\fIauthcommunity\fR. +.IP "authgroup TYPES [\-s MODEL] GROUP [LEVEL [OID | \-V VIEW [CONTEXT]]]" +is a companion to the \fIauthuser\fR directive, specifying access +for a particular group (defined using the \fIgroup\fR directive as usual). +Both \fIauthuser\fR and \fIauthgroup\fR default to authenticated requests - +LEVEL can also be specified as \fInoauth\fR or \fIpriv\fR to allow +unauthenticated requests, or require encryption respectively. +Both \fIauthuser\fR and \fIauthgroup\fR directives also default to configuring +access for SNMPv3/USM requests - use the '\-s' flag to specify an alternative +security model (using the same values as for \fIaccess\fR above). +.IP "authaccess TYPES [\-s MODEL] GROUP VIEW [LEVEL [CONTEXT]]" +also configures the access for a particular group, +specifying the name and type of view to apply. The MODEL and LEVEL fields +are interpreted in the same way as for \fIauthgroup\fR. +If CONTEXT is specified, access is configured within this SNMPv3 context +(or contexts with this prefix if the CONTEXT field ends with '*'). +Otherwise the default context ("") is used. +.IP "setaccess GROUP CONTEXT MODEL LEVEL PREFIX VIEW TYPES" +is a direct equivalent to the original \fIaccess\fR directive, typically +listing the view types as \fIread\fR or \fIread,write\fR as appropriate. +(or see 'snmptrapd.conf(5)' for other possibilities). +All other fields have the same interpretation as with \fIaccess\fR. +.SH SYSTEM INFORMATION +Most of the information reported by the Net-SNMP agent is retrieved +from the underlying system, or dynamically configured via SNMP SET requests +(and retained from one run of the agent to the next). +However, certain MIB objects can be configured or controlled via +the \fIsnmpd.conf(5)\fR file. +.SS System Group +Most of the scalar objects in the 'system' group can be configured +in this way: +.IP "sysLocation STRING" +.IP "sysContact STRING" +.IP "sysName STRING" +set the system location, system contact or system name +(\fCsysLocation.0\fR, \fCsysContact.0\fR and \fCsysName.0\fR) for the agent respectively. +Ordinarily these objects are writable via suitably authorized SNMP SET +requests. However, specifying one of these directives makes the +corresponding object read-only, and attempts to SET it will result in +a \fInotWritable\fR error response. +.IP "sysServices NUMBER" +sets the value of the \fCsysServices.0\fR object. +For a host system, a good value is 72 (application + end-to-end layers). +If this directive is not specified, then no value will be reported +for the \fCsysServices.0\fR object. +.IP "sysDescr STRING" +.IP "sysObjectID OID" +sets the system description or object ID for the agent. +Although these MIB objects are not SNMP-writable, these directives can be +used by a network administrator to configure suitable values for them. +.SS Interfaces Group +.IP "interface NAME TYPE SPEED" +can be used to provide appropriate type and speed settings for +interfaces where the agent fails to determine this information correctly. +TYPE is a type value as given in the IANAifType\-MIB, +and can be specified numerically or by name (assuming this MIB is loaded). +.IP "interface_fadeout TIMEOUT" +specifies, for how long the agent keeps entries in \fCifTable\fR after +appropriate interfaces have been removed from system (typically various ppp, +tap or tun interfaces). Timeout value is in seconds. Default value is 300 +(=5 minutes). +.IP "interface_replace_old yes" +can be used to remove already existing entries in \fCifTable\fR when an +interface with the same name appears on the system. E.g. when ppp0 interface +is removed, it is still listed in the table for \fIinterface_fadeout\fR +seconds. This option ensures, that the old ppp0 interface is removed even +before the \fIinterface_fadeout\fR timeour when new ppp0 (with different +\fCifIndex\fR) shows up. +.SS Host Resources Group +This requires that the agent was built with support for the +\fIhost\fR module (which is now included as part of the default build +configuration on the major supported platforms). +.\" +.\" XXX - .IP "scandisk STRING" +.\" +.IP "ignoreDisk STRING" +controls which disk devices are scanned as part of populating the +\fChrDiskStorageTable\fR (and \fChrDeviceTable\fR). +The HostRes implementation code includes a list of disk device patterns +appropriate for the current operating system, some of which may cause +the agent to block when trying to open the corresponding disk devices. +This might lead to a timeout when walking these tables, possibly +resulting in inconsistent behaviour. This directive can be used +to specify particular devices (either individually or wildcarded) +that should not be checked. +.RS +.IP "Note:" +Please consult the source (\fIhost/hr_disk.c\fR) and check for the +\fIAdd_HR_Disk_entry\fR calls relevant for a particular O/S +to determine the list of devices that will be scanned. +.RE +.IP +The pattern can include one or more wildcard expressions. +See \fIsnmpd.examples(5)\fR for illustration of the wildcard syntax. +.IP "skipNFSInHostResources true" +controls whether NFS and NFS-like file systems should be omitted +from the hrStorageTable (true or 1) or not (false or 0, which is the default). +If the Net-SNMP agent gets hung on NFS-mounted filesystems, you +can try setting this to '1'. +.IP "storageUseNFS [1|2]" +controls how NFS and NFS-like file systems should be reported +in the hrStorageTable. +as 'Network Disks' (1) or 'Fixed Disks' (2) +Historically, the Net-SNMP agent has reported such file systems +as 'Fixed Disks', and this is still the default behaviour. +Setting this directive to '1' reports such file systems as +\'Network Disks', as required by the Host Resources MIB. +.IP "realStorageUnits" +controlls how the agent reports hrStorageAllocationUnits, hrStorageSize and +hrStorageUsed in hrStorageTable. +For big storage drives with small allocation units the agent re-calculates +these values so they all fit Integer32 and +hrStorageAllocationUnits x hrStorageSize +gives real size of the storage. +.RS +.IP "Example:" +Linux xfs 16TB filesystem with 4096 bytes large blocks will be +reported as hrStorageAllocationUnits = 8192 and hrStorageSize = 2147483647, +so 8192 x 2147483647 gives real size of the filesystem (=16 TB). +.RE +.IP +Setting this directive to '1' turns off +this calculation and the agent reports real hrStorageAllocationUnits, but it +might report wrong hrStorageSize for big drives because the value won't fit into +Integer32. In this case, hrStorageAllocationUnits x hrStorageSize won't give +real size of the storage. +.SS Process Monitoring +The \fChrSWRun\fR group of the Host Resources MIB provides +information about individual processes running on the local system. +The \fCprTable\fR of the UCD\-SNMP\-MIB complements this by reporting +on selected services (which may involve multiple processes). +This requires that the agent was built with support for the +\fIucd\-snmp/proc\fR module (which is included as part of the +default build configuration). +.IP "proc NAME [MAX [MIN]]" +monitors the number of processes called NAME (as reported by PSCMD) +running on the local system. +.IP +If the number of NAMEd processes is less than MIN or greater than MAX, +then the corresponding \fCprErrorFlag\fR instance will be +set to 1, and a suitable description message reported via the +\fCprErrMessage\fR instance. +.RS +.IP "Note:" +This situation will \fBnot\fR automatically trigger a trap to report +the problem - see the DisMan Event MIB section later. +.RE +.IP +If neither MAX nor MIN are specified, they will +default to \fBinfinity\fR and 1 respectively ("at least one"). +If only MAX is specified, MIN will default to 0 ("no more than MAX"). +If MAX is 0 (and MIN is not), this indicates infinity ("at least MIN"). +If both MAX and MIN are 0, this indicates a process that should \fBnot\fP +be running. +.IP "procfix NAME PROG ARGS" +registers a command that can be run to fix errors with the given +process NAME. This will be invoked when the corresponding +\fCprErrFix\fR instance is set to 1. +.RS +.IP "Note:" +This command will \fBnot\fR be invoked automatically. +.\" XXX - but see the DisMan Event MIB section later ??? +.RE +.IP +The \fIprocfix\fR directive must be specified \fBafter\fR the matching +\fIproc\fR directive, and cannot be used on its own. +.PP +If no \fIproc\fR directives are defined, then walking the +\fCprTable\fR will fail (\fInoSuchObject\fI). +.SS Disk Usage Monitoring +This requires that the agent was built with support for the +\fIucd\-snmp/disk\fR module (which is included as part of the +default build configuration). +.IP "disk PATH [ MINSPACE | MINPERCENT% ]" +monitors the disk mounted at PATH for available disk space. +.IP +The minimum threshold can either be specified in kB (MINSPACE) or +as a percentage of the total disk (MINPERCENT% with a '%' character), +defaulting to 100kB if neither are specified. +If the free disk space falls below this threshold, +then the corresponding \fCdskErrorFlag\fR instance will be +set to 1, and a suitable description message reported via the +\fCdskErrorMsg\fR instance. +.RS +.IP "Note:" +This situation will \fBnot\fR automatically trigger a trap to report +the problem - see the DisMan Event MIB section later. +.RE +.IP "includeAllDisks MINPERCENT%" +configures monitoring of all disks found on the system, +using the specified (percentage) threshold. +The threshold for individual disks can be adjusted using suitable +\fIdisk\fR directives (which can come either before or after the +\fIincludeAllDisks\fR directive). +.RS +.IP "Note:" +Whether \fIdisk\fR directives appears before or after \fIincludeAllDisks\fR +may affect the indexing of the \fCdskTable\fR. +.RE +.IP +Only one \fIincludeAllDisks\fR directive should be specified - any +subsequent copies will be ignored. +.IP +The list of mounted disks will be determined when the agent starts using the +setmntent(3) and getmntent(3), or fopen(3) and getmntent(3), or +setfsent(3) and getfsent(3) system calls. If none of the above +system calls are available then the root partition "/" +(which is assumed to exist on any UNIX based system) will be monitored. +Disks mounted after the agent has started will not be monitored. +.\" +.\" XXX - unless the config is re-read ?? +.\" +.PP +If neither any \fIdisk\fR directives or \fIincludeAllDisks\fR are defined, +then walking the \fCdskTable\fR will fail (\fInoSuchObject\fI). +.SS Disk I/O Monitoring +This requires that the agent was built with support for the +\fIucd\-snmp/diskio\fR module (which is not included as part of the +default build configuration). +.PP +By default, all block devices known to the operating system are +included in the diskIOTable. On platforms other than Linux, this module +has no configuration directives. +.PP +On Linux systems, it is possible to exclude several classes of block +devices from the diskIOTable in order to avoid cluttering the table with +useless zero statistics for pseudo-devices that often are not in use but +are configured by default to exist in most recent Linux distributions. +.IP "diskio_exclude_fd yes" +Excludes all Linux floppy disk block devices, whose names start with "fd", +e.g. "fd0" +.IP "diskio_exclude_loop yes" +Excludes all Linux loopback block devices, whose names start with "loop", +e.g. "loop0" +.IP "diskio_exclude_ram yes" +Excludes all LInux ramdisk block devices, whose names start with "ram", e.g. +"ram0" +.SS System Load Monitoring +This requires that the agent was built with support for either the +\fIucd\-snmp/loadave\fR module or the \fIucd\-snmp/memory\fR module +respectively (both of which are included as part of the +default build configuration). +.IP "load MAX1 [MAX5 [MAX15]]" +monitors the load average of the local system, specifying +thresholds for the 1-minute, 5-minute and 15-minute averages. +If any of these loads exceed the associated maximum value, +then the corresponding \fClaErrorFlag\fR instance will be +set to 1, and a suitable description message reported via the +\fClaErrMessage\fR instance. +.RS +.IP "Note:" +This situation will \fBnot\fR automatically trigger a trap to report +the problem - see the DisMan Event MIB section later. +.RE +.IP +If the MAX15 threshold is omitted, it will default to the MAX5 value. +If both MAX5 and MAX15 are omitted, they will default to the MAX1 value. +If this directive is not specified, all three thresholds will +default to a value of DEFMAXLOADAVE. +.IP +If a threshold value of 0 is given, the agent will not report errors +via the relevant \fClaErrorFlag\fR or \fClaErrMessage\fR instances, +regardless of the current load. +.PP +Unlike the \fIproc\fR and \fIdisk\fR directives, walking the +walking the \fClaTable\fR will succeed (assuming the +\fIucd\-snmp/loadave\fR module was configured into the agent), +even if the \fIload\fR directive is not present. +.IP "swap MIN " +monitors the amount of swap space available on the local system. +If this falls below the specified threshold (MIN kB), +then the \fImemErrorSwap\fR object will be set to 1, +and a suitable description message reported via \fImemSwapErrorMsg\fR. +.RS +.IP "Note:" +This situation will \fBnot\fR automatically trigger a trap to report +the problem - see the DisMan Event MIB section later. +.RE +If this directive is not specified, the default threshold is 16 MB. +.SS Log File Monitoring +This requires that the agent was built with support for either the +\fIucd\-snmp/file\fR or \fIucd\-snmp/logmatch\fR modules respectively +(both of which are included as part of the +default build configuration). +.IP "file FILE [MAXSIZE]" +monitors the size of the specified file (in kB). +If MAXSIZE is specified, and the size of the file exceeds +this threshold, then the corresponding \fCfileErrorFlag\fR +instance will be set to 1, and a suitable description message reported +via the \fCfileErrorMsg\fR instance. +.RS +.IP "Note:" +This situation will \fBnot\fR automatically trigger a trap to report +the problem - see the DisMan Event MIB section later. +.RE +.IP +Note: A maximum of 20 files can be monitored. +.IP +Note: If no \fIfile\fR directives are defined, then walking the +\fCfileTable\fR will fail (\fInoSuchObject\fR). +.IP "logmatch NAME FILE CYCLETIME REGEX" +monitors the specified file for occurances of the specified +pattern REGEX. The file position is stored internally so the entire file +is only read initially, every subsequent pass will only read the new lines +added to the file since the last read. +.RS +.IP NAME +name of the logmatch instance (will appear as logMatchName under +logMatch/logMatchTable/logMatchEntry/logMatchName in the ucd\-snmp MIB tree) +.IP FILE +absolute path to the logfile to be monitored. Note that this path +can contain date/time directives (like in the UNIX 'date' command). See the +manual page for 'strftime' for the various directives accepted. +.IP CYCLETIME +time interval for each logfile read and internal variable update in seconds. +Note: an SNMPGET* operation will also trigger an immediate logfile read and +variable update. +.IP REGEX +the regular expression to be used. Note: DO NOT enclose the regular expression +in quotes even if there are spaces in the expression as the quotes will also +become part of the pattern to be matched! +.RE +.IP +Example: +.RS +.IP +logmatch apache\-GETs /usr/local/apache/logs/access.log\-%Y\-%m\-%d 60 GET.*HTTP.* +.IP +This logmatch instance is named 'apache\-GETs', uses 'GET.*HTTP.*' as its +regular expression and it will monitor the file named +(assuming today is May 6th 2009): '/usr/local/apache/logs/access.log\-2009\-05\-06', +tomorrow it will look for 'access.log\-2009\-05\-07'. The logfile is read every 60 +seconds. +.RE +.IP +Note: A maximum of 250 logmatch directives can be specified. +.IP +Note: If no \fIlogmatch\fR directives are defined, then walking the +\fClogMatchTable\fR will fail (\fInoSuchObject\fI). +.SH "ACTIVE MONITORING" +The usual behaviour of an SNMP agent is to wait for incoming SNMP requests +and respond to them - if no requests are received, an agent will typically +not initiate any actions. This section describes various directives that +can configure \fIsnmpd\fR to take a more active role. +.SS "Notification Handling" +.IP "trapcommunity STRING" +defines the default community string to be used when sending traps. +Note that this directive must be used prior to any community-based +trap destination directives that need to use it. +.IP "trapsink HOST [COMMUNITY [PORT]]" +.IP "trap2sink HOST [COMMUNITY [PORT]]" +.IP "informsink HOST [COMMUNITY [PORT]]" +define the address of a notification receiver that should be sent +SNMPv1 TRAPs, SNMPv2c TRAP2s, or SNMPv2 INFORM notifications respectively. +See the section +.B LISTENING ADDRESSES +in the +.I snmpd(8) +manual page for more information about the format of listening +addresses. +If COMMUNITY is not specified, the most recent \fItrapcommunity\fR +string will be used. +.IP +If the transport address does not include an explicit +port specification, then PORT will be used. +If this is not specified, the well known SNMP trap +port (162) will be used. +.RS +.IP Note: +This mechanism is being deprecated, and the listening port +should be specified via the transport specification HOST instead. +.RE +.IP +If several sink directives are specified, multiple +copies of each notification (in the appropriate formats) +will be generated. +.RS +.IP Note: +It is \fBnot\fR normally appropriate to list two (or all three) +sink directives with the same destination. +.RE +.IP "trapsess [SNMPCMD_ARGS] HOST" +provides a more generic mechanism for defining notification destinations. +.I "SNMPCMD_ARGS" +should be the command-line options required for an equivalent +\fIsnmptrap\fR (or \fIsnmpinform\fR) command to send the desired notification. +The option \fI\-Ci\fR can be used (with \fI\-v2c\fR or \fI\-v3\fR) to generate +an INFORM notification rather than an unacknowledged TRAP. +.IP +This is the appropriate directive for defining SNMPv3 trap receivers. +See +http://www.net\-snmp.org/tutorial/tutorial\-5/commands/snmptrap\-v3.html +for more information about SNMPv3 notification behaviour. +.IP "authtrapenable {1|2}" +determines whether to generate authentication failure traps +(\fIenabled(1)\fR) or not (\fIdisabled(2)\fR - the default). +Ordinarily the corresponding MIB +object (\fCsnmpEnableAuthenTraps.0\fR) is read-write, but specifying +this directive makes this object read-only, and attempts to set the +value via SET requests will result in a \fInotWritable\fR error response. +.RE +.IP "v1trapaddress HOST" +defines the agent address, which is inserted into SNMPv1 TRAPs. Arbitrary local +IPv4 address is chosen if this option is ommited. This option is useful mainly +when the agent is visible from outside world by specific address only (e.g. +because of network address translation or firewall). +.SS "DisMan Event MIB" +The previous directives can be used to configure where traps should +be sent, but are not concerned with \fIwhen\fR to send such traps +(or what traps should be generated). This is the domain of the +Event MIB - developed by the Distributed Management (DisMan) +working group of the IETF. +.PP +This requires that the agent was built with support for the +\fIdisman/event\fR module (which is now included as part of the +default build configuration for the most recent distribution). +.RS +.IP "Note:" +The behaviour of the latest implementation differs in some minor +respects from the previous code - nothing too significant, but +existing scripts may possibly need some minor adjustments. +.RE +.IP "iquerySecName NAME" +.IP "agentSecName NAME" +specifies the default SNMPv3 username, to be used when making internal +queries to retrieve any necessary information (either for evaluating +the monitored expression, or building a notification payload). +These internal queries always use SNMPv3, even if normal querying +of the agent is done using SNMPv1 or SNMPv2c. +.IP +Note that this user must also be explicitly created (\fIcreateUser\fR) +and given appropriate access rights (e.g. \fIrouser\fR). This +directive is purely concerned with defining \fIwhich\fR user should +be used - not with actually setting this user up. +.\" +.\" XXX - Should it create the user as well? +.\" +.\" .IP "iqueryVersion " +.\" .IP "iquerySecLevel " +.\" +.IP "monitor [OPTIONS] NAME EXPRESSION" +defines a MIB object to monitor. +If the EXPRESSION condition holds (see below), then this will trigger +the corresponding event, and either send a notification or apply +a SET assignment (or both). +Note that the event will only be triggered once, when the expression +first matches. This monitor entry will not fire again until the +monitored condition first becomes false, and then matches again. +NAME is an administrative name for this expression, and is used for +indexing the \fCmteTriggerTable\fR (and related tables). +Note also that such monitors use an internal SNMPv3 request to retrieve +the values being monitored (even if normal agent queries typically use +SNMPv1 or SNMPv2c). See the \fIiquerySecName\fP token described above. +.IP "\fIEXPRESSION\fR" +There are three types of monitor expression supported by the Event MIB - +existence, boolean and threshold tests. +.RS +.IP "OID | ! OID | != OID" +defines an \fIexistence(0)\fR monitor test. +A bare OID specifies a \fIpresent(0)\fR test, which will fire when +(an instance of) the monitored OID is created. +An expression of the form \fI! OID\fR specifies an \fIabsent(1)\fR test, +which will fire when the monitored OID is delected. +An expression of the form \fI!= OID\fR specifies a \fIchanged(2)\fR test, +which will fire whenever the monitored value(s) change. +Note that there \fBmust\fP be whitespace before the OID token. +.IP "OID OP VALUE" +defines a \fIboolean(1)\fR monitor test. +OP should be one of the defined +comparison operators (!=, ==, <, <=, >, >=) and VALUE should be an +integer value to compare against. +Note that there \fBmust\fP be whitespace around the OP token. +A comparison such as \fCOID !=0\fP will not be handled correctly. +.IP "OID MIN MAX [DMIN DMAX]" +defines a \fIthreshold(2)\fR monitor test. +MIN and MAX are integer values, specifying lower and upper thresholds. +If the value of the monitored OID falls below the lower threshold (MIN) +or rises above the upper threshold (MAX), then the monitor entry will +trigger the corresponding event. +.IP +Note that the rising threshold event will only be re-armed when +the monitored value falls below the \fBlower\fR threshold (MIN). +Similarly, the falling threshold event will be re-armed by +the upper threshold (MAX). +.IP +The optional parameters DMIN and DMAX configure a pair of +similar threshold tests, but working with the delta +differences between successive sample values. +.RE +.IP "\fIOPTIONS\fR" +There are various options to control the behaviour of the monitored +expression. These include: +.RS +.IP "\-D" +indicates that the expression should be evaluated using delta differences +between sample values (rather than the values themselves). +.IP "\-d OID" +.IP "\-di OID" +specifies a discontinuity marker for validating delta differences. +A \fI\-di\fR object instance will be used exactly as given. +A \fI\-d\fR object will have the instance subidentifiers from the +corresponding (wildcarded) expression object appended. +If the \fI\-I\fR flag is specified, then there is no difference +between these two options. +.IP +This option also implies \fI\-D\fR. +.IP "\-e EVENT" +specifies the event to be invoked when this monitor entry is triggered. +If this option is not given, the monitor entry will generate one +of the standard notifications defined in the DISMAN\-EVENT\-MIB. +.IP "\-I" +indicates that the monitored expression should be applied to the +specified OID as a single instance. By default, the OID will +be treated as a wildcarded object, and the monitor expanded +to cover all matching instances. +.IP "\-i OID" +.IP "\-o OID" +define additional varbinds to be added to the notification payload +when this monitor trigger fires. +For a wildcarded expression, the suffix of the matched instance +will be added to any OIDs specified using \fI\-o\fR, while OIDs +specified using \fI\-i\fR will be treated as exact instances. +If the \fI\-I\fR flag is specified, then there is no difference +between these two options. +.IP +See \fIstrictDisman\fR for details of the ordering of notification payloads. +.IP "\-r FREQUENCY" +monitors the given expression every FREQUENCY, where FREQUENCY is in +seconds or optionally suffixed by one of s (for seconds), m (for +minutes), h (for hours), d (for days), or w (for weeks). By default, +the expression will be evaluated every 600s (10 minutes). +.IP "\-S" +indicates that the monitor expression should \fInot\fR be evaluated +when the agent first starts up. The first evaluation will be done +once the first repeat interval has expired. +.IP "\-s" +indicates that the monitor expression \fIshould\fR be evaluated when the +agent first starts up. This is the default behaviour. +.RS +.IP "Note:" +Notifications triggered by this initial evaluation will be sent +\fIbefore\fR the \fCcoldStart\fR trap. +.RE +.IP "\-u SECNAME" +specifies a security name to use for scanning the local host, +instead of the default \fIiquerySecName\fR. +Once again, this user must be explicitly created and given +suitable access rights. +.RE +.IP "notificationEvent ENAME NOTIFICATION [\-m] [\-i OID | \-o OID ]*" +defines a notification event named ENAME. +This can be triggered from a given \fImonitor\fR entry by specifying +the option \fI\-e ENAME\fR (see above). +NOTIFICATION should be the OID of the NOTIFICATION\-TYPE definition +for the notification to be generated. +.IP +If the \fI\-m\fR option is given, the notification payload will +include the standard varbinds as specified in the OBJECTS clause +of the notification MIB definition. +This option must come \fBafter\fR the NOTIFICATION OID +(and the relevant MIB file must be available and loaded by the agent). +Otherwise, these varbinds must +be listed explicitly (either here or in the corresponding +\fImonitor\fR directive). +.IP +The \fI\-i OID\fR and \fI\-o OID\fR options specify additional +varbinds to be appended to the notification payload, after the +standard list. +If the monitor entry that triggered this event involved a +wildcarded expression, the suffix of the matched instance +will be added to any OIDs specified using \fI\-o\fR, while OIDs +specified using \fI\-i\fR will be treated as exact instances. +If the \fI\-I\fR flag was specified to the \fImonitor\fR directive, +then there is no difference between these two options. +.IP "setEvent ENAME [\-I] OID = VALUE " +defines a set event named ENAME, assigning the (integer) VALUE +to the specified OID. +This can be triggered from a given \fImonitor\fR entry by specifying +the option \fI\-e ENAME\fR (see above). +.IP +If the monitor entry that triggered this event involved a +wildcarded expression, the suffix of the matched instance +will normally be added to the OID. +If the \fI\-I\fR flag was specified to either of the +\fImonitor\fR or \fIsetEvent\fR directives, the +specified OID will be regarded as an exact single instance. +.IP "strictDisman yes" +The definition of SNMP notifications states that the +varbinds defined in the OBJECT clause should come first +(in the order specified), followed by any "extra" varbinds +that the notification generator feels might be useful. +The most natural approach would be to associate these +mandatory varbinds with the \fInotificationEvent\fR entry, +and append any varbinds associated with the monitor entry +that triggered the notification to the end of this list. +This is the default behaviour of the Net-SNMP Event MIB implementation. +.IP +Unfortunately, the DisMan Event MIB specifications actually +state that the trigger-related varbinds should come \fBfirst\fR, +followed by the event-related ones. This directive can be used to +restore this strictly-correct (but inappropriate) behaviour. +.RS +.IP "Note:" +Strict DisMan ordering may result in generating invalid notifications +payload lists if the \fInotificationEvent \-n\fR flag is used together +with \fImonitor \-o\fR (or \fI\-i\fR) varbind options. +.RE +.IP +If no \fImonitor\fR entries specify payload varbinds, +then the setting of this directive is irrelevant. +.IP "linkUpDownNotifications yes" +will configure the Event MIB tables to monitor the \fCifTable\fR +for network interfaces being taken up or down, and triggering +a \fIlinkUp\fR or \fIlinkDown\fR notification as appropriate. +.IP +This is exactly equivalent to the configuration: +.RS +.IP +.nf +notificationEvent linkUpTrap linkUp ifIndex ifAdminStatus ifOperStatus +notificationEvent linkDownTrap linkDown ifIndex ifAdminStatus ifOperStatus + +monitor \-r 60 \-e linkUpTrap "Generate linkUp" ifOperStatus != 2 +monitor \-r 60 \-e linkDownTrap "Generate linkDown" ifOperStatus == 2 +.fi +.RE +.IP "defaultMonitors yes" +will configure the Event MIB tables to monitor the various +\fCUCD\-SNMP\-MIB\fR tables for problems (as indicated by +the appropriate \fCxxErrFlag\fR column objects). +.IP +This is exactly equivalent to the configuration: +.RS +.IP +.nf +monitor \-o prNames \-o prErrMessage "process table" prErrorFlag != 0 +monitor \-o memErrorName \-o memSwapErrorMsg "memory" memSwapError != 0 +monitor \-o extNames \-o extOutput "extTable" extResult != 0 +monitor \-o dskPath \-o dskErrorMsg "dskTable" dskErrorFlag != 0 +monitor \-o laNames \-o laErrMessage "laTable" laErrorFlag != 0 +monitor \-o fileName \-o fileErrorMsg "fileTable" fileErrorFlag != 0 +.fi +.RE +.PP +In both these latter cases, the snmpd.conf must also contain a +\fIiquerySecName\fR directive, together with a corresponding +\fIcreateUser\fR entry and suitable access control configuration. +.SS "DisMan Schedule MIB" +The DisMan working group also produced a mechanism for scheduling +particular actions (a specified SET assignment) at given times. +This requires that the agent was built with support for the +\fIdisman/schedule\fR module (which is included as part of the +default build configuration for the most recent distribution). +.PP +There are three ways of specifying the scheduled action: +.IP "repeat FREQUENCY OID = VALUE" +configures a SET assignment of the (integer) VALUE to the MIB instance +OID, to be run every FREQUENCY seconds, where FREQUENCY is in +seconds or optionally suffixed by one of s (for seconds), m (for +minutes), h (for hours), d (for days), or w (for weeks). +.IP "cron MINUTE HOUR DAY MONTH WEEKDAY OID = VALUE" +configures a SET assignment of the (integer) VALUE to the MIB instance +OID, to be run at the times specified by the fields MINUTE to WEEKDAY. +These follow the same pattern as the equivalent \fIcrontab(5)\fR fields. +.RS +.IP "Note:" +These fields should be specified as a (comma-separated) list of numeric +values. Named values for the MONTH and WEEKDAY fields are not supported, +and neither are value ranges. A wildcard match can be specified as '*'. +.RE +.IP +The DAY field can also accept negative values, to indicate days counting +backwards from the end of the month. +.IP "at MINUTE HOUR DAY MONTH WEEKDAY OID = VALUE" +configures a one-shot SET assignment, to be run at the first matching +time as specified by the fields MINUTE to WEEKDAY. The interpretation +of these fields is exactly the same as for the \fIcron\fR directive. +.SS "Data Delivery via Notfiications" +Note: this functionality is only available if the +\fIdeliver/deliverByNotify\fR mib module was complied in to the agent +.PP +In some situations it may be advantageous to deliver SNMP data over +SNMP Notifications (TRAPs and INFORMs) rather than the typical process +of having the manager issue requests for the data (via GETs and +GETNEXTs). Reasons for doing this are numerous, but frequently corner +cases. The most common reason for wanting this behaviour might be to +monitor devices that reside behind NATs or Firewalls that prevent +incoming SNMP traffic. +.PP +It should be noted that although most management software is capable +of logging notifications, very little (if any) management software +will updated their "knowledge database" based on the contents of SNMP +notifications. IE, it won't (for example) update the interface +traffic counter history that is used to produce graphs. Most larger +network management packages have a separate database for storing data +received via SNMP requests (GETs and GETNEXTs) vs those received from +notifications. Researching the capabilities of your management +station software is required before assuming this functionality will +solve your data delivery requirements. +.PP +Notifications generated via this mechanism will be sent to the +standard set of configured notification targets. See the +"Notification Handling" section of this document for further +information. +.IP "deliverByNotify [\-p] [\-m] [\-s MAXSIZE] FREQUENCY OID" +This directive tells the SNMP agent to self-walk the \fIOID\fR, +collect all the data and send it out every \fIFREQUENCY\fR seconds, +where FREQUENCY is in seconds or optionally suffixed by one of s (for +seconds), m (for minutes), h (for hours), d (for days), or w (for +weeks). By default scalars are included in the notification that +specify the how often the notification will be sent (unless the +\fI\-p\fR option is specified) and which message number of how many +messages a particular notification is (unless \fI\-m\fR is specified). +To break the notifications into manageable packet sizes, use the +\fI\-s\fR flag to specify the approximate maximum number of bytes that +a notification message should be limited to. If more than +\fIMAXSIZE\fR of bytes is needed then multiple notifications will be +sent to deliver the data. Note that the calculations for ensuring the +maximum size is met are approximations and thus it can be absolutely +guaranteed they'll be under that size, so leave a padding buffer if it +is critical that you avoid fragmentation. A value of \-1 indicates +force everything into a single message no matter how big it is. +.IP +Example usage: the following will deliver the contents of the ifTable +once an hour and the contents of the system group once every 2 hours: +.RS +.nf + +deliverByNotify 3600 ifTable +deliverByNotify 7200 system +.fi +.RE +.IP "deliverByNotifyMaxPacketSize SIZEINBYTES" +Sets the default notification size limit (see the \fI\-s\fR flag above). +.IP "deliverByNotifyOid OID" +.IP "deliverByNotifyFrequencyOid OID" +.IP "deliverByNotifyMessageNumberOid OID" +.IP "deliverByNotifyMaxMessageNumberOid OID" +These set the data OID that the notification will be sent under, the +scalar OID, the message number OID, and the maximum message number +OID. These default to objects in the NET\-SNMP\-PERIODIC\-NOTIFY\-MIB. +.SH "EXTENDING AGENT FUNCTIONALITY" +One of the first distinguishing features of the original UCD suite was +the ability to extend the functionality of the agent - not just by +recompiling with code for new MIB modules, but also by configuring the running agent to +report additional information. There are a number of techniques to +support this, including: +.IP \(bu +running external commands (\fIexec\fR, \fIextend\fR, \fIpass\fR) +.IP \(bu +loading new code dynamically (embedded perl, \fIdlmod\fR) +.IP \(bu +communicating with other agents (\fIproxy\fR, SMUX, AgentX) +.SS "Arbitrary Extension Commands" +The earliest extension mechanism was the ability to run arbitrary +commands or shell scripts. Such commands do not need to be aware of +SNMP operations, or conform to any particular behaviour - the MIB +structures are designed to accommodate any form of command output. +Use of this mechanism requires that the agent was built with support for the +\fIucd\-snmp/extensible\fR and/or \fIagent/extend\fR modules (which +are both included as part of the default build configuration). +.IP "exec [MIBOID] NAME PROG ARGS" +.IP "sh [MIBOID] NAME PROG ARGS" +invoke the named PROG with arguments of ARGS. By default the exit +status and first line of output from the command will be reported via +the \fCextTable\fR, discarding any additional output. +.RS +.IP Note: +Entries in this table appear in the order they are read from the +configuration file. This means that adding new \fIexec\fR (or \fIsh\fR) +directives and restarting the agent, may affect the indexing of other +entries. +.RE +.IP +The PROG argument for \fIexec\fR directives must be a full path +to a real binary, as it is executed via the exec() system call. +To invoke a shell script, use the \fIsh\fR directive instead. +.IP +If MIBOID is specified, then the results will be rooted at this point +in the OID tree, returning the exit statement as MIBOID.ERRORFLAG.0 +and the entire command output in a pseudo-table based at +MIBNUM.ERRORMSG - with one 'row' for each line of output. +.RS +.IP Note: +The layout of this "relocatable" form of \fIexec\fR (or \fIsh\fR) output +does not strictly form a valid MIB structure. This mechanism is being +deprecated - please see the \fIextend\fR directive (described below) instead. +.RE +.IP +The agent does not cache the exit status or output of the executed program. +.\" +.\" XXX - Is this still true ?? +.\" +.IP "execfix NAME PROG ARGS" +registers a command that can be invoked on demand - typically to respond +to or fix errors with the corresponding \fIexec\fR or \fIsh\fR entry. +When the \fIextErrFix\fR instance for a given NAMEd entry is set to the +integer value of 1, this command will be called. +.RS +.IP "Note:" +This directive can only be used in combination with a corresponding +\fIexec\fR or \fIsh\fR directive, which must be defined first. +Attempting to define an unaccompanied \fIexecfix\fR directive will fail. +.RE +.PP +\fIexec\fR and \fIsh\fR extensions can only be configured via the +snmpd.conf file. They cannot be set up via SNMP SET requests. +.IP "extend [MIBOID] NAME PROG ARGS" +works in a similar manner to the \fIexec\fR directive, but with a number +of improvements. The MIB tables (\fInsExtendConfigTable\fR +etc) are indexed by the NAME token, so are unaffected by the order in +which entries are read from the configuration files. +There are \fItwo\fR result tables - one (\fInsExtendOutput1Table\fR) +containing the exit status, the first line and full output (as a single string) +for each \fIextend\fR entry, and the other (\fInsExtendOutput2Table\fR) +containing the complete output as a series of separate lines. +.IP +If MIBOID is specified, then the configuration and result tables will be rooted +at this point in the OID tree, but are otherwise structured in exactly +the same way. This means that several separate \fIextend\fR +directives can specify the same MIBOID root, without conflicting. +.IP +The exit status and output is cached for each entry individually, and +can be cleared (and the caching behaviour configured) +using the \fCnsCacheTable\fR. +.IP "extendfix NAME PROG ARGS" +registers a command that can be invoked on demand, by setting the +appropriate \fInsExtendRunType\fR instance to the value +\fIrun-command(3)\fR. Unlike the equivalent \fIexecfix\fR, +this directive does not need to be paired with a corresponding +\fIextend\fR entry, and can appear on its own. +.PP +Both \fIextend\fR and \fIextendfix\fR directives can be configured +dynamically, using SNMP SET requests to the NET\-SNMP\-EXTEND\-MIB. +.SS "MIB-Specific Extension Commands" +The first group of extension directives invoke arbitrary commands, +and rely on the MIB structure (and management applications) having +the flexibility to accommodate and interpret the output. This is a +convenient way to make information available quickly and simply, but +is of no use when implementing specific MIB objects, where the extension +must conform to the structure of the MIB (rather than vice versa). +The remaining extension mechanisms are all concerned with such +MIB-specific situations - starting with "pass-through" scripts. +Use of this mechanism requires that the agent was built with support for the +\fIucd\-snmp/pass\fR and \fIucd\-snmp/pass_persist\fR modules (which +are both included as part of the default build configuration). +.IP "pass [\-p priority] MIBOID PROG" +will pass control of the subtree rooted at MIBOID to the specified +PROG command. GET and GETNEXT requests for OIDs within this tree will +trigger this command, called as: +.RS +.IP +PROG \-g OID +.IP +PROG \-n OID +.RE +.IP +respectively, where OID is the requested OID. +The PROG command should return the response varbind as three separate +lines printed to stdout - the first line should be the OID of the returned +value, the second should be its TYPE (one of the text strings +.B integer, gauge, counter, timeticks, ipaddress, objectid, +or +.B string +), and the third should be the value itself. +.IP +If the command cannot return an appropriate varbind - e.g the specified +OID did not correspond to a valid instance for a GET request, or there +were no following instances for a GETNEXT - then it should exit without +producing any output. This will result in an SNMP \fInoSuchName\fR +error, or a \fInoSuchInstance\fR exception. +.RS +.RS +.IP "Note:" +The SMIv2 type \fBcounter64\fR +and SNMPv2 \fInoSuchObject\fR exception are not supported. +.RE +.RE +.IP +A SET request will result in the command being called as: +.RS +.IP +PROG \-s OID TYPE VALUE +.RE +.IP +where TYPE is one of the tokens listed above, indicating the type of the +value passed as the third parameter. +.\".RS +.\".RS +.\".IP "Note:" +.\".B counter +.\"(and +.\".B counter64 +.\") syntax objects are not valid for SETs +.\".RE +.\".RE +.IP +If the assignment is successful, the PROG command should exit without producing +any output. Errors should be indicated by writing one of the strings +.B not-writable, +or +.B wrong-type +to stdout, +and the agent will generate the appropriate error response. +.RS +.RS +.IP "Note:" +The other SNMPv2 errors are not supported. +.RE +.RE +.IP +In either case, the command should exit once it has finished processing. +Each request (and each varbind within a single request) will trigger +a separate invocation of the command. +.IP +The default registration priority is 127. This can be +changed by supplying the optional \-p flag, with lower priority +registrations being used in preference to higher priority values. +.IP "pass_persist [\-p priority] MIBOID PROG" +will also pass control of the subtree rooted at MIBOID to the specified +PROG command. However this command will continue to run after the initial +request has been answered, so subsequent requests can be processed without +the startup overheads. +.IP +Upon initialization, PROG will be passed the string "PING\\n" on stdin, +and should respond by printing "PONG\\n" to stdout. +.IP +For GET and GETNEXT requests, PROG will be passed two lines on stdin, +the command (\fIget\fR or \fIgetnext\fR) and the requested OID. +It should respond by printing three lines to stdout - +the OID for the result varbind, the TYPE and the VALUE itself - +exactly as for the \fIpass\fR directive above. +If the command cannot return an appropriate varbind, +it should print print "NONE\\n" to stdout (but continue running). +.IP +For SET requests, PROG will be passed three lines on stdin, +the command (\fIset\fR) and the requested OID, +followed by the type and value (both on the same line). +If the assignment is successful, the command should print +"DONE\\n" to stdout. +Errors should be indicated by writing one of the strings +.B not\-writable, +.B wrong\-type, +.B wrong\-length, +.B wrong\-value +or +.B inconsistent\-value +to stdout, +and the agent will generate the appropriate error response. +In either case, the command should continue running. +.IP +The registration priority can be changed using the optional +\-p flag, just as for the \fIpass\fR directive. +.PP +\fIpass\fR and \fIpass_persist\fR extensions can only be configured via the +snmpd.conf file. They cannot be set up via SNMP SET requests. +.\" +.\" XXX - caching ?? +.\" +.SS "Embedded Perl Support" +Programs using the previous extension mechanisms can be written in any convenient +programming language - including perl, which is a common choice for +pass-through extensions in particular. However the Net-SNMP agent +also includes support for embedded perl technology (similar to +\fImod_perl\fR for the Apache web server). This allows the agent +to interpret perl scripts directly, thus avoiding the overhead of +spawning processes and initializing the perl system when a request is received. +.PP +Use of this mechanism requires that the agent was built with support for the embedded +perl mechanism, which is not part of the default build environment. It +must be explicitly included by specifying the '\-\-enable\-embedded\-perl' +option to the configure script when the package is first built. +.PP +If enabled, the following directives will be recognised: +.IP "disablePerl true" +will turn off embedded perl support entirely (e.g. if there are problems +with the perl installation). +.IP "perlInitFile FILE" +loads the specified initialisation file (if present) +immediately before the first \fIperl\fR directive is parsed. +If not explicitly specified, the agent will look for the default +initialisation file DATADIR/snmp/snmp_perl.pl. +.IP +The default initialisation file +creates an instance of a \fCNetSNMP::agent\fR object - a variable +\fC$agent\fR which can be used to register perl-based MIB handler routines. +.IP "perl EXPRESSION" +evaluates the given expression. This would typically register a +handler routine to be called when a section of the OID tree was +requested: +.RS +.RS +.nf +\fCperl use Data::Dumper; +perl sub myroutine { print "got called: ",Dumper(@_),"\\n"; } +perl $agent\->register('mylink', '.1.3.6.1.8765', \\&myroutine);\fR +.fi +.RE +.RE +.IP +This expression could also source an external file: +.RS +.RS +\fCperl 'do /path/to/file.pl';\fR +.RE +.RE +.IP +or perform any other perl-based processing that might be required. +.\" +.\" Link to more examples +.\" +.SS Dynamically Loadable Modules +Most of the MIBs supported by the Net-SNMP agent are implemented as +C code modules, which were compiled and linked into the agent libraries +when the suite was first built. Such implementation modules can also be +compiled independently and loaded into the running agent once it has +started. Use of this mechanism requires that the agent was built with support for the +\fIucd\-snmp/dlmod\fR module (which is included as part of the default +build configuration). +.IP "dlmod NAME PATH" +will load the shared object module from the file PATH (an absolute +filename), and call the initialisation routine \fIinit_NAME\fR. +.RS +.IP "Note:" +If the specified PATH is not a fully qualified filename, it will +be interpreted relative to LIBDIR/snmp/dlmod, and \fC.so\fR +will be appended to the filename. +.RE +.PP +This functionality can also be configured using SNMP SET requests +to the UCD\-DLMOD\-MIB. +.SS "Proxy Support" +Another mechanism for extending the functionality of the agent +is to pass selected requests (or selected varbinds) to another +SNMP agent, which can be running on the same host (presumably +listening on a different port), or on a remote system. +This can be viewed either as the main agent delegating requests to +the remote one, or acting as a proxy for it. +Use of this mechanism requires that the agent was built with support for the +\fIucd\-snmp/proxy\fR module (which is included as part of the +default build configuration). +.IP "proxy [\-Cn CONTEXTNAME] [SNMPCMD_ARGS] HOST OID [REMOTEOID]" +will pass any incoming requests under OID to the agent listening +on the port specified by the transport address HOST. +See the section +.B LISTENING ADDRESSES +in the +.I snmpd(8) +manual page for more information about the format of listening +addresses. +.RS +.IP "Note:" +To proxy the entire MIB tree, use the OID .1.3 +(\fBnot\fR the top-level .1) +.RE +.PP +The \fISNMPCMD_ARGS\fR should provide sufficient version and +administrative information to generate a valid SNMP request +(see \fIsnmpcmd(1)\fR). +.IP "Note:" +The proxied request will \fInot\fR use the administrative +settings from the original request. +.RE +.PP +If a CONTEXTNAME is specified, this will register the proxy +delegation within the named context in the local agent. +Defining multiple \fIproxy\fR directives for the same OID but +different contexts can be used to query several remote agents +through a single proxy, by specifying the appropriate SNMPv3 +context in the incoming request (or using suitable configured +community strings - see the \fIcom2sec\fR directive). +.PP +Specifying the REMOID parameter will map the local MIB tree +rooted at OID to an equivalent subtree rooted at REMOID +on the remote agent. +.SS SMUX Sub-Agents +The Net-SNMP agent supports the SMUX protocol (RFC 1227) to communicate +with SMUX-based subagents (such as \fIgated\fR, \fIzebra\fR or \fIquagga\fR). +Use of this mechanism requires that the agent was built with support for the +\fIsmux\fR module, which is not part of the default build environment, and +must be explicitly included by specifying the '\-\-with\-mib\-modules=smux' +option to the configure script when the package is first built. +.RS +.IP "Note:" +This extension protocol has been officially deprecated in +favour of AgentX (see below). +.RE +.IP "smuxpeer OID PASS" +will register a subtree for SMUX-based processing, to be +authenticated using the password PASS. If a subagent +(or "peer") connects to the agent and registers this subtree +.\" +.\" Or a subtree of this subtree ?? +.\" +then requests for OIDs within it will be passed to that +SMUX subagent for processing. +.IP +A suitable entry for an OSPF routing daemon (such as \fIgated\fR, +\fIzebra\fR or \fIquagga\fR) might be something like +.RS +.RS +.I smuxpeer .1.3.6.1.2.1.14 ospf_pass +.RE +.RE +.IP "smuxsocket <IPv4-address>" +defines the IPv4 address for SMUX peers to communicate with the Net-SNMP agent. +The default is to listen on all IPv4 interfaces ("0.0.0.0"), unless the +package has been configured with "\-\-enable\-local\-smux" at build time, which +causes it to only listen on 127.0.0.1 by default. SMUX uses the well-known +TCP port 199. +.PP +Note the Net-SNMP agent will only operate as a SMUX \fImaster\fR +agent. It does not support acting in a SMUX subagent role. +.SS AgentX Sub-Agents +The Net-SNMP agent supports the AgentX protocol (RFC 2741) in +both master and subagent roles. +Use of this mechanism requires that the agent was built with support for the +\fIagentx\fR module (which is included as part of the +default build configuration), and also that this support is +explicitly enabled (e.g. via the \fIsnmpd.conf\fR file). +.PP +There are two directives specifically relevant to running as +an AgentX master agent: +.IP "master agentx" +will enable the AgentX functionality and cause the agent to +start listening for incoming AgentX registrations. +This can also be activated by specifying the '\-x' command-line +option (to specify an alternative listening socket). +.IP "agentXPerms SOCKPERMS [DIRPERMS [USER|UID [GROUP|GID]]]" +Defines the permissions and ownership of the AgentX Unix Domain socket, +and the parent directories of this socket. +SOCKPERMS and DIRPERMS must be octal digits (see +.I chmod(1) +). By default this socket will only be accessible to subagents which +have the same userid as the agent. +.PP +There is one directive specifically relevant to running as +an AgentX sub-agent: +.IP "agentXPingInterval NUM" +will make the subagent try and reconnect every NUM seconds to the +master if it ever becomes (or starts) disconnected. +.PP +The remaining directives are relevant to both AgentX master +and sub-agents: +.IP "agentXSocket [<transport-specifier>:]<transport-address>[,...]" +defines the address the master agent listens at, or the subagent +should connect to. +The default is the Unix Domain socket \fCAGENTX_SOCKET\fR. +Another common alternative is \fCtcp:localhost:705\fR. +See the section +.B LISTENING ADDRESSES +in the +.I snmpd(8) +manual page for more information about the format of addresses. +.RS +.IP "Note:" +Specifying an AgentX socket does \fBnot\fR automatically enable +AgentX functionality (unlike the '\-x' command-line option). +.RE +.IP "agentXTimeout NUM" +defines the timeout period (NUM seconds) for an AgentX request. +Default is 1 second. NUM also be specified with a suffix of one of s +(for seconds), m (for minutes), h (for hours), d (for days), or w (for +weeks). +.IP "agentXRetries NUM" +defines the number of retries for an AgentX request. +Default is 5 retries. +.PP +net-snmp ships with both C and Perl APIs to develop your own AgentX +subagent. +.SH "OTHER CONFIGURATION" +.IP "override [\-rw] OID TYPE VALUE" +This directive allows you to override a particular OID with a +different value (and possibly a different type of value). The \-rw +flag will allow snmp SETs to modify it's value as well. (note that if +you're overriding original functionality, that functionality will be +entirely lost. Thus SETS will do nothing more than modify the +internal overridden value and will not perform any of the original +functionality intended to be provided by the MIB object. It's an +emulation only.) An example: +.RS +.IP +\fCoverride sysDescr.0 octet_str "my own sysDescr"\fR +.RE +.IP +That line will set the sysDescr.0 value to "my own sysDescr" as well +as make it modifiable with SNMP SETs as well (which is actually +illegal according to the MIB specifications). +.IP +Note that care must be taken when using this. For example, if you try +to override a property of the 3rd interface in the ifTable with a new +value and later the numbering within the ifTable changes it's index +ordering you'll end up with problems and your modified value won't +appear in the right place in the table. +.IP +Valid TYPEs are: integer, uinteger, octet_str, object_id, counter, +null (for gauges, use "uinteger"; for bit strings, use "octet_str"). +Note that setting an object to "null" effectively delete's it as being +accessible. No VALUE needs to be given if the object type is null. +.IP +More types should be available in the future. +.PP +If you're trying to figure out aspects of the various mib modules +(possibly some that you've added yourself), the following may help you +spit out some useful debugging information. First off, please read +the snmpd manual page on the \-D flag. Then the following +configuration snmpd.conf token, combined with the \-D flag, can produce +useful output: +.IP "injectHandler HANDLER modulename [beforeThis]" +This will insert new handlers into the section of the mib tree +referenced by "modulename". If "beforeThis" is specified then the +module will be injected before the named module. This is useful for +getting a handler into the exact right position in the chain. +.IP +The types of handlers available for insertion are: +.RS +.IP stash_cache +Caches information returned from the lower level. This +greatly help the performance of the agent, at the cost +of caching the data such that its no longer "live" for +30 seconds (in this future, this will be configurable). +Note that this means snmpd will use more memory as well +while the information is cached. Currently this only +works for handlers registered using the table_iterator +support, which is only a few mib tables. To use it, +you need to make sure to install it before the +table_iterator point in the chain, so to do this: + + \fCinjectHandler stash_cache NAME table_iterator\fR + +If you want a table to play with, try walking the +\fCnsModuleTable\fR with and without this injected. + +.IP debug +Prints out lots of debugging information when +the \-Dhelper:debug flag is passed to the snmpd +application. + +.IP read_only +Forces turning off write support for the given module. + +.IP serialize +If a module is failing to handle multiple requests +properly (using the new 5.0 module API), this will force +the module to only receive one request at a time. + +.IP bulk_to_next +If a module registers to handle getbulk support, but +for some reason is failing to implement it properly, +this module will convert all getbulk requests to +getnext requests before the final module receives it. +.RE +.IP "dontLogTCPWrappersConnects" +If the \fBsnmpd\fR was compiled with TCP Wrapper support, it +logs every connection made to the agent. This setting disables +the log messages for accepted connections. Denied connections will +still be logged. +.IP "Figuring out module names" +To figure out which modules you can inject things into, +run \fBsnmpwalk\fR on the \fCnsModuleTable\fR which will give +a list of all named modules registered within the agent. +.SS Internal Data tables +.IP "table NAME" +.\" XXX: To Document +.IP "add_row NAME INDEX(ES) VALUE(S)" +.\" XXX: To Document +.SH NOTES +.IP o +The Net-SNMP agent can be instructed to re-read the various configuration files, +either via an \fBsnmpset\fR assignment of integer(1) to +\fCUCD\-SNMP\-MIB::versionUpdateConfig.0\fR (.1.3.6.1.4.1.2021.100.11.0), +or by sending a \fBkill \-HUP\fR signal to the agent process. +.IP o +All directives listed with a value of "yes" actually accept a range +of boolean values. These will accept any of \fI1\fR, \fIyes\fR or +\fItrue\fR to enable the corresponding behaviour, +or any of \fI0\fR, \fIno\fR or \fIfalse\fR to disable it. +The default in each case is for the feature to be turned off, so these +directives are typically only used to enable the appropriate behaviour. +.SH "EXAMPLE CONFIGURATION FILE" +See the EXAMPLE.CONF file in the top level source directory for a more +detailed example of how the above information is used in real +examples. +.SH "FILES" +SYSCONFDIR/snmp/snmpd.conf +.SH "SEE ALSO" +snmpconf(1), snmpusm(1), snmp.conf(5), snmp_config(5), snmpd(8), EXAMPLE.conf, netsnmp_config_api(3). +.\" Local Variables: +.\" mode: nroff +.\" End: diff --git a/man/snmpd.examples.5.def b/man/snmpd.examples.5.def new file mode 100644 index 0000000..b4125d6 --- /dev/null +++ b/man/snmpd.examples.5.def @@ -0,0 +1,655 @@ +.TH SNMPD.EXAMPLES 5 "13 Oct 2006" VVERSIONINFO "Net-SNMP" +.SH NAME +snmpd.examples - example configuration for the Net-SNMP agent +.SH DESCRIPTION +The +.I snmpd.conf(5) +man page defines the syntax and behaviour of the various +configuration directives that can be used to control the +operation of the Net-SNMP agent, and the management information +it provides. +.PP +This companion man page illustrates these directives, showing +some practical examples of how they might be used. +.SH AGENT BEHAVIOUR +.SS "Listening addresses" +The default agent behaviour (listing on the standard SNMP UDP port on +all interfaces) is equivalent to the directive: +.RS +agentaddress udp:161 +.RE +or simply +.RS +agentaddress 161 +.RE +The agent can be configured to \fIonly\fR accept requests sent to the +local loopback interface (again listening on the SNMP UDP port), using: +.RS +agentaddress localhost:161 \fI# (udp implicit)\fR +.RE +or +.RS +agentaddress 127.0.0.1 \fI# (udp and standard port implicit)\fR +.RE +It can be configured to accept both UDP and TCP requests (over both IPv4 +and IPv6), using: +.RS +agentaddress udp:161,tcp:161,udp6:161,tcp6:161 +.RE +.\" +.\" Can the agent handle the same port for both IPv4 & IPv6 +.\" +Other combinations are also valid. +.SS "Run-time privileges" +The agent can be configured to relinquish any privileged access once it +has opened the initial listening ports. Given a suitable "snmp" group +(defined in \fI/etc/group\fR), this could be done using the directives: +.RS +.nf +agentuser nobody +agentgroup snmp +.fi +.RE +A similar effect could be achieved using numeric UID and/or GID values: +.RS +.nf +agentuser #10 +agentgroup #10 +.fi +.RE +.\" +.\" What effect will/may this have on the information returned. +.\" ??? Mention this in the main man page. +.\" +.SS SNMPv3 Configuration +Rather than being generated pseudo-randomly, +the engine ID for the agent could be calculated based on the MAC address +of the second network interface (\fIeth1\fR), using the directives: +.RS +engineIDType 3 +engineIDNic eth1 +.RE +or it could be calculated from the (first) IP address, using: +.RS +engineIDType 1 +.RE +or it could be specified explicitly, using: +.RS +engineID "XXX - WHAT FORMAT" +.RE +.\" +.\" Does engineID override the other directives, or what? +.\" +.SH ACCESS CONTROL +.SS SNMPv3 Users +The following directives will create three users, all using exactly +the same authentication and encryption settings: +.RS +.nf +createUser me MD5 "single pass phrase" +createUser myself MD5 "single pass phrase" DES +createUser andI MD5 "single pass phrase" DES "single pass phrase" +.fi +.RE +Note that this defines three \fIdistinct\fR users, who could be granted +different levels of access. Changing the passphrase for any one of +these would not affect the other two. +.PP +Separate pass phrases can be specified for authentication and +encryption: +.RS +createUser onering SHA "to rule them all" AES "to bind them" +.RE +Remember that these \fIcreateUser\fR directives should be defined in the +PERSISTENT_DIRECTORY/snmpd.conf file, rather than the usual location. +.RE +.\" +.\" ??? Illustrate "\-e", "\-l" and "\-m" forms ?? +.\" +.SS Traditional Access Control +The SNMPv3 users defined above can be granted access to the full +MIB tree using the directives: +.RS +.nf +rouser me +rwuser onering +.fi +.RE +Or selective access to individual subtrees using: +.RS +.nf +rouser myself .1.3.6.1.2 +rwuser andI system +.fi +.RE +.PP +Note that a combination repeating the same user, such as: +.RS +.nf +rouser onering +rwuser onering +.fi +.RE +should \fBnot\fR be used. This would configure the user \fIonering\fR +with read-only access (and ignore the \fIrwuser\fR entry altogether). +The same holds for the community-based directives. +.PP +The directives: +.RS +.nf +rocommunity public +rwcommunity private +.fi +.RE +would define the commonly-expected read and write community strings +for SNMPv1 and SNMPv2c requests. This behaviour is \fBnot\fR +configured by default, and would need to be set up explicitly. +.RS +.IP Note: +It would also be a very good idea to change \fIprivate\fR to something +a little less predictable! +.RE +.PP +A slightly less vulnerable configuration might restrict what information +could be retrieved: +.RS +rocommunity public default system +.RE +or the management systems that settings could be manipulated from: +.RS +rwcommunity private 10.10.10.0/24 +.RE +or a combination of the two. +.SS VACM Configuration +This last pair of settings are equivalent to the full VACM definitions: +.RS +.nf +\fI# sec.name source community\fR +com2sec public default public +com2sec mynet 10.10.10.0/24 private +com2sec6 mynet fec0::/64 private + +\fI# sec.model sec.name\fR +group worldGroup v1 public +group worldGroup v2c public +group myGroup v1 mynet +group myGroup v2c mynet + +\fI# incl/excl subtree [mask]\fR +view all included .1 +view sysView included system + +\fI# context model level prefix read write notify (unused)\fR +access worldGroup "" any noauth exact system none none +access myGroup "" any noauth exact all all none +.fi +.RE +.PP +There are several points to note in this example: +.PP +The \fIgroup\fR directives must be repeated for +both SNMPv1 and SNMPv2c requests. +.PP +The \fIcom2sec\fR security name is distinct from the community +string that is mapped to it. They can be the same ("public") +or different ("mynet"/"private") - but what appears in the +\fIgroup\fR directive is the security name, regardless of +the original community string. +.PP +Both of the \fIview\fR directives are defining simple OID +subtrees, so neither of these require an explicit mask. +The same holds for the "combined subtree2 view defined below. +In fact, a mask field is only needed when defining row slices +across a table (or similar views), and can almost always be omitted. +.PP +In general, it is advisible not to mix traditional and VACM-based +access configuration settings, as these can sometimes interfere +with each other in unexpected ways. Choose a particular style +of access configuration, and stick to it. +.\" +.\" Mention/use hardwired views '_all_' and '_none_' +.\" +.\" Illustrate other, more flexible configurations +.\" including SNMPv3 access. +.\" +.SS Typed-View Configuration +A similar configuration could also be configured as follows: +.RS +.nf +view sys2View included system +view sys2View included .1.3.6.1.2.1.25.1 + +authcommunity read public default \-v sys2View +authcommunity read,write private 10.10.10.0/8 +.fi +.RE +.PP +This mechanism allows multi-subtree (or other non-simple) views to +be used with the one-line \fIrocommunity\fR style of configuration. +.PP +It would also support configuring "write-only" access, should this +be required. +.\" +.\" Expand this example +.\" +.SH SYSTEM INFORMATION +.SS System Group +The full contents of the 'system' group (with the exception of \fCsysUpTime\fR) +can be explicitly configured using: +.RS +.nf +\fI# Override 'uname \-a' and hardcoded system OID - inherently read-only values\fR +sysDescr Universal Turing Machine mk I +sysObjectID .1.3.6.1.4.1.8072.3.2.1066 + +\fI# Override default values from 'configure' - makes these objects read-only\fR +sysContact Alan.Turing@pre\-cs.man.ac.uk +sysName tortoise.turing.com +sysLocation An idea in the mind of AT + +\fI# Standard end-host behaviour\fR +sysServices 72 +.fi +.RE +.SS Host Resources Group +The list of devices probed for potential inclusion in the +\fChrDiskStorageTable\fR (and \fChrDeviceTable\fR) can be amended using +any of the following directives: +.RS +ignoredisk /dev/rdsk/c0t2d0 +.RE +which prevents the device \fI/dev/rdsk/c0t2d0\fR from being scanned, +.RS +.nf +ignoredisk /dev/rdsk/c0t[!6]d0 +ignoredisk /dev/rdsk/c0t[0\-57\-9a\-f]d0 +.fi +.RE +either of which prevents all devices \fI/dev/rdsk/c0t\fRX\fId0\fR +(except .../\fIc0t6d0\fR) from being scanned, +.RS +ignoredisk /dev/rdsk/c1* +.RE +which prevents all devices whose device names start with \fI/dev/rdsk/c1\fR +from being scanned, or +.RS +ignoredisk /dev/rdsk/c?t0d0 +.RE +which prevents all devices \fI/dev/rdsk/c\fRX\fIt0d0\fR +(where 'X' is any single character) from being scanned. +.SS Process Monitoring +The list of services running on a system can be monitored +(and provision made for correcting any problems), using: +.RS +.nf +\fI# At least one web server process must be running at all times\fR +proc httpd +procfix httpd /etc/rc.d/init.d/httpd restart + +\fI# There should never be more than 10 mail processes running +# (more implies a probable mail storm, so shut down the mail system)\fR +proc sendmail 10 +procfix sendmail /etc/rc.d/init.d/sendmail stop + +\fI# There should be a single network management agent running +# ("There can be only one")\fR +proc snmpd 1 1 +.fi +.RE +Also see the "DisMan Event MIB" section later on. +.SS Disk Usage Monitoring +The state of disk storage can be monitored using: +.RS +.nf +includeAllDisks 10% +disk /var 20% +disk /usr 3% +\fI# Keep 100 MB free for crash dumps\fR +disk /mnt/crash 100000 +.fi +.RE +.SS System Load Monitoring +A simple check for an overloaded system might be: +.RS +load 10 +.RE +A more refined check (to allow brief periods of heavy use, +but recognise sustained medium-heavy load) might be: +.RS +load 30 10 5 +.RE +.SS Log File Monitoring +.I TODO +.RS +file FILE [MAXSIZE] +.RE +.RS +logmatch NAME PATH CYCLETIME REGEX +.RE +.SH "ACTIVE MONITORING" +.SS "Notification Handling" +Configuring the agent to report invalid access attempts might be done by: +.RS +.nf +authtrapenable 1 +trapcommunity public +trap2sink localhost +.fi +.RE +Alternatively, the second and third directives could be combined +(and an acknowledgement requested) using: +.RS +informsink localhost public +.RE +A configuration with repeated sink destinations, such as: +.RS +.nf +trapsink localhost +trap2sink localhost +informsink localhost +.fi +.RE +should \fBNOT\fR be used, as this will cause multiple copies +of each trap to be sent to the same trap receiver. +.PP +.I "TODO - discuss SNMPv3 traps" +.RS +trapsess \fIsnmpv3 options\fR localhost:162 +.RE +.PP +.I "TODO - mention trapd access configuration" + +.SS "DisMan Event MIB" +The simplest configuration for active self-monitoring of +the agent, by the agent, for the agent, is probably: +.RS +.nf +\fI# Set up the credentials to retrieve monitored values\fR +createUser _internal MD5 "the first sign of madness" +iquerySecName _internal +rouser _internal + +\fI# Active the standard monitoring entries\fR +defaultMonitors yes +linkUpDownNotifications yes + +\fI# If there's a problem, then tell someone!\fR +trap2sink localhost +.fi +.RE +.PP +The first block sets up a suitable user for retrieving the +information to by monitored, while the following pair of +directives activates various built-in monitoring entries. +.PP +Note that the DisMan directives are not themselves sufficient to +actively report problems - there also needs to be a suitable +destination configured to actually send the resulting notifications to. +.PP +A more detailed monitor example is given by: +.RS +monitor \-u me \-o hrSWRunName "high process memory" hrSWRunPerfMem > 10000 +.RE +.PP +This defines an explicit boolean monitor entry, looking for any process +using more than 10MB of active memory. Such processes will be reported +using the (standard) DisMan trap \fCmteTriggerFired\fR, +but adding an extra (wildcarded) varbind \fChrSWRunName\fR. +.PP +This entry also specifies an explicit user (\fIme\fR, as defined +earlier) for retrieving the monitored values, and building the trap. +.PP +Objects that could potentially fluctuate around the specified level +are better monitored using a threshold monitor entry: +.RS +monitor \-D \-r 10 "network traffic" ifInOctets 1000000 5000000 +.RE +.PP +This will send a \fCmteTriggerRising\fR trap whenever the incoming +traffic rises above (roughly) 500 kB/s on any network interface, +and a corresponding \fCmteTriggerFalling\fR trap when it falls below +100 kB/s again. +.PP +Note that this monitors the deltas between successive samples (\fI\-D\fR) +rather than the actual sample values themselves. The same effect +could be obtained using: +.RS +monitor \-r 10 "network traffic" ifInOctets \- \- 1000000 5000000 +.RE +.PP +The \fIlinkUpDownNotifications\fR directive above is broadly +equivalent to: +.RS +.nf +notificationEvent linkUpTrap linkUp ifIndex ifAdminStatus ifOperStatus +notificationEvent linkDownTrap linkDown ifIndex ifAdminStatus ifOperStatus + +monitor \-r 60 \-e linkUpTrap "Generate linkUp" ifOperStatus != 2 +monitor \-r 60 \-e linkDownTrap "Generate linkDown" ifOperStatus == 2 +.fi +.RE +.PP +This defines the traps to be sent (using \fInotificationEvent\fR), +and explicitly references the relevant notification in the corresponding +monitor entry (rather than using the default DisMan traps). +.PP +The \fIdefaultMonitors\fR directive above is equivalent to a series +of (boolean) monitor entries: +.RS +.nf +monitor \-o prNames \-o prErrMessage "procTable" prErrorFlag != 0 +monitor \-o memErrorName \-o memSwapErrorMsg "memory" memSwapError != 0 +monitor \-o extNames \-o extOutput "extTable" extResult != 0 +monitor \-o dskPath \-o dskErrorMsg "dskTable" dskErrorFlag != 0 +monitor \-o laNames \-o laErrMessage "laTable" laErrorFlag != 0 +monitor \-o fileName \-o fileErrorMsg "fileTable" fileErrorFlag != 0 +.fi +.RE +and will send a trap whenever any of these entries indicate a problem. +.PP +An alternative approach would be to automatically invoke the corresponding +"fix" action: +.RS +.nf +setEvent prFixIt prErrFix = 1 +monitor \-e prFixIt "procTable" prErrorFlag != 0 +.fi +.RE +(and similarly for any of the other \fIdefaultMonitor\fR entries). +.SS "DisMan Schedule MIB" +The agent could be configured to reload its configuration +once an hour, using: +.RS +repeat 3600 versionUpdateConfig.0 = 1 +.RE +.PP +Alternatively this could be configured to be run at specific +times of day (perhaps following rotation of the logs): +.RS +cron 10 0 * * * versionUpdateConfig.0 = 1 +.RE +.PP +The one-shot style of scheduling is rather less common, but the +secret SNMP virus could be activated on the next occurance of Friday 13th using: +.RS +at 13 13 13 * 5 snmpVirus.0 = 1 +.RE +.SH "EXTENDING AGENT FUNCTIONALITY" +.SS "Arbitrary Extension Commands" +.I "Old Style" +.RS +.nf +exec [MIBOID] NAME PROG ARGS" +sh [MIBOID] NAME PROG ARGS" +execfix NAME PROG ARGS" +.fi +.RE +.I "New Style" +.RS +.nf +extend [MIBOID] NAME PROG ARGS" +extendfix [MIBOID] NAME PROG ARGS" +.fi +.RE +.SS "MIB-Specific Extension Commands" +.I One-Shot +.RS +"pass [\-p priority] MIBOID PROG" +.RE +.IP +.I Persistent +.RS +"pass_persist [\-p priority] MIBOID PROG" +.RE +.SS "Embedded Perl Support" +If embedded perl support is enabled in the agent, the default +initialisation is equivalent to the directives: +.RS +.nf +disablePerl false +perlInitFile DATADIR/snmp/snmp_perl.pl +.fi +.RE +The main mechanism for defining embedded perl scripts is the +\fIperl\fR directive. A very simple (if somewhat pointless) +MIB handler could be registered using: +.RS +.nf +perl use Data::Dumper; +perl sub myroutine { print "got called: ",Dumper(@_),"\\n"; } +perl $agent\->register('mylink', '.1.3.6.1.8765', \\&myroutine); +.fi +.RE +.PP +This relies on the \fI$agent\fR object, defined in the example +\fCsnmp_perl.pl\fR file. +.PP +A more realistic MIB handler might be: +.RS +.nf +\fIXXX - WHAT ???\fR +.fi +.RE +Alternatively, this code could be stored in an external file, +and loaded using: +.RS +perl 'do DATADIR/snmp/perl_example.pl'; +.RE +.\" +.\" XXX - does this last entry need the quotes ?? +.\" +.SS Dynamically Loadable Modules +.I TODO +.RS +dlmod NAME PATH" +.RE +.SS "Proxy Support" +A configuration for acting as a simple proxy for two other +SNMP agents (running on remote systems) might be: +.RS +.nf +com2sec \-Cn rem1context rem1user default remotehost1 +com2sec \-Cn rem2context rem2user default remotehost2 + +proxy \-Cn rem1context \-v 1 -c public remotehost1 .1.3 +proxy \-Cn rem2context \-v 1 -c public remotehost2 .1.3 +.fi +.RE +(plus suitable access control entries). +.PP +The same \fIproxy\fR directives would also work with +(incoming) SNMPv3 requests, which can specify a context directly. +It would probably be more sensible to use contexts of +\fIremotehost1\fR and \fIremotehost2\fR - the names above were +chosen to indicate how these directives work together. +.PP +Note that the administrative settings for the proxied request +are specified explicitly, and are independent of the settings +from the incoming request. +.PP +An alternative use for the \fiproxy\fR directive is to pass +part of the OID tree to another agent (either on a remote host +or listening on a different port on the same system), +while handling the rest internally: +.RS +proxy \-v 1 \-c public localhost:6161 .1.3.6.1.4.1.99 +.RE +This mechanism can be used to link together two separate SNMP agents. +.PP +A less usual approach is to map one subtree into a different area +of the overall MIB tree (either locally or on a remote system): +.RS +.nf +\fI# uses SNMPv3 to access the MIB tree .1.3.6.1.2.1.1 on 'remotehost' +# and maps this to the local tree .1.3.6.1.3.10\fR +proxy \-v 3 \-l noAuthNoPriv \-u user remotehost .1.3.6.1.3.10 .1.3.6.1.2.1.1 +.fi +.RE +.SS SMUX Sub-Agents +.RS +.nf +smuxsocket 127.0.0.1 +smuxpeer .1.3.6.1.2.1.14 ospf_pass +.fi +.RE +.SS AgentX Sub-Agents +The Net-SNMP agent could be configured to operate as an AgentX master +agent (listening on a non-standard named socket, and running using +the access privileges defined earlier), using: +.RS +.nf +master agentx +agentXSocket /tmp/agentx/master +agentXPerms 0660 0550 nobody snmp +.fi +.RE +.\" +.\" XXX - do numeric UID/GID take a leading '#' ?? +.\" why not?? +.\" +A sub-agent wishing to connect to this master agent would need +the same \fIagentXSocket\fR directive, or the equivalent code: +.RS +.nf +netsnmp_ds_set_string(NETSNMP_DS_APPLICATION_ID, NETSNMP_DS_AGENT_X_SOCKET, + "/tmp/agentx/master"); +.fi +.RE +.PP +A loopback networked AgentX configuration could be set up using: +.RS +.nf +agentXSocket tcp:localhost:705 +agentXTimeout 5 +agentXRetries 2 +.fi +.RE +on the master side, and: +.RS +.nf +agentXSocket tcp:localhost:705 +agentXTimeout 10 +agentXRetries 1 +agentXPingInterval 600 +.fi +.RE +on the client. +.PP +Note that the timeout and retry settings can be asymmetric +for the two directions, and the sub-agent can poll the master agent +at regular intervals (600s = every 10 minutes), to ensure the +connection is still working. +.SH "OTHER CONFIGURATION" +.RS +override sysDescr.0 octet_str "my own sysDescr" +.RE +.RS +injectHandler stash_cache NAME table_iterator +.RE +.SH "FILES" +SYSCONFDIR/snmp/snmpd.conf +.SH "SEE ALSO" +snmpconf(1), snmpd.conf(5), snmp.conf(5), snmp_config(5), snmpd(8), EXAMPLE.conf, netsnmp_config_api(3). +.\" Local Variables: +.\" mode: nroff +.\" End: diff --git a/man/snmpd.internal.5.def b/man/snmpd.internal.5.def new file mode 100644 index 0000000..81147c7 --- /dev/null +++ b/man/snmpd.internal.5.def @@ -0,0 +1,92 @@ +.TH SNMPD.INTERNAL 5 "06 Dec 2005" VVERSIONINFO "Net-SNMP" +.SH NAME +snmpd.internal - internal configuration of the Net-SNMP agent +.SH DESCRIPTION +The +.I snmpd.conf(5) +man page defines the syntax and behaviour of the main +configuration directives that can be used to control the +operation of the Net-SNMP agent, and the management information +it provides. +.PP +However there are several other configuration directives +(many of which, though not all, start with a leading underscore) +that are recognised by the agent. These are typically used +to retain configuration across agent restarts, and are not +intended for direct user access. +This man page list these directives, giving a brief indication +of where they are used. For full details - see the relevant source +files. If you can't follow that source, you probably shouldn't +be fiddling with these directives! +.SH AGENT BEHAVIOUR +.IP "quit" +.\" .SS "Listening addresses" +.\" .SS "Run-time privileges" +.\" .SS SNMPv3 Configuration +.SH ACCESS CONTROL +.\" .SS SNMPv3 Users +.\" .SS Traditional Access Control +.SS VACM Configuration +.IP "vacmView / vacmGroup / vacmAccess " +These directives are used to retain dynamically configured +access control settings. +.\" .SS Typed-View Configuration +.SH SYSTEM INFORMATION +.SS System Group +.IP "setSerialNo " +This directive is used to implement the advisory lock object +\fCsnmpSetSerialNo\fR. +.IP "psyslocation / psyscontact / psysname " +These directives are used to retain dynamically configured +system settings. +They will be overridden by the corresponding +\fIsysLocation\fR, \fIsysContact\fR and \fIsysName\fR directives. +.\" .SS Host Resources Group +.\" .SS Process Monitoring +.\" .SS Disk Usage Monitoring +.\" .SS System Load Monitoring +.\" .SS Log File Monitoring +.SH "ACTIVE MONITORING" +.SS "Notification Handling" +.IP "pauthtrapenable" +This directive is used to retain the dynamically configured +setting of whether the agent should generate authenticationFailure +traps. +It will be overridden by the corresponding +\fIauthtrapenable\fR directive. +.IP "snmpNotify*Table " +.IP "targetAddr / targetParams " +These directives are used to retain dynamically configured +notification destination settings. +.SS "DisMan Event MIB" +.IP "_mteE*Table, _mteOTable, _mteT*Table " +These directives are used to retain dynamically configured +event, object and monitor trigger settings. +.IP "mteObjectsTable / mteTriggerTable " +These directives are for compatibility with the previous +\fIdisman/event-mib\fR implementation. +.SS "DisMan Schedule MIB" +.IP "_schedTable " +This directive is used to retain dynamically configured +scheduled events. +.SH "EXTENDING AGENT FUNCTIONALITY" +.SS "Arbitrary Extension Commands" +.IP "extend-sh " +.IP "exec2 / sh2 / execFix2 " +These directives were defined by analogy with equivalent directives +in the previous \fIucd-snmp/extensible\fR implementation. +They are deprecated, and should not be used. +.\" .SS "MIB-Specific Extension Commands" +.\" .SS "Embedded Perl Support" +.\" .SS Dynamically Loadable Modules +.\" .SS "Proxy Support" +.\" .SS SMUX Sub-Agents +.\" .SS AgentX Sub-Agents +.\" .SH "OTHER CONFIGURATION" +.SH "FILES" +SYSCONFDIR/snmp/snmpd.conf +.SH "SEE ALSO" +snmpconf(1), snmpd.conf(5), snmp.conf(5), snmp_config(5), snmpd(8), EXAMPLE.conf, netsnmp_config_api(3). +.\" Local Variables: +.\" mode: nroff +.\" End: diff --git a/man/snmpdelta.1.def b/man/snmpdelta.1.def new file mode 100644 index 0000000..fe80b57 --- /dev/null +++ b/man/snmpdelta.1.def @@ -0,0 +1,160 @@ +.\" Portions of this file are subject to the following copyright. See +.\" the Net-SNMP's COPYING file for more details and other copyrights +.\" that may apply: +.\" /*********************************************************** +.\" Portions of this file are copyrighted by: +.\" Copyright Copyright 2003 Sun Microsystems, Inc. All rights reserved. +.\" Use is subject to license terms specified in the COPYING file +.\" distributed with the Net-SNMP package. +.\" ******************************************************************/ +.TH SNMPDELTA 1 "25 Jul 2003" VVERSIONINFO "Net-SNMP" +.SH NAME +snmpdelta \- Monitor delta differences in SNMP Counter values +.SH SYNOPSIS +.B snmpdelta +[ COMMON OPTIONS ] [\-Cf] [ \-Ct ] [ \-Cs ] [ \-CS ] [ \-Cm ] [ \-CF configfile ] [ \-Cl ] [ \-Cp period ] [ \-CP Peaks ] [ \-Ck ] [ \-CT ] AGENT OID [ OID ... ] +.SH "DESCRIPTION" +.B snmpdelta +will monitor the specified integer valued OIDs, and report changes +over time. +.PP +AGENT identifies a target SNMP agent, which is instrumented +to monitor the given objects. At its simplest, the AGENT +specification will consist of a hostname or an IPv4 +address. In this situation, the command will attempt +communication with the agent, using UDP/IPv4 to port 161 +of the given target host. See snmpcmd(1) for a full list of +the possible formats for AGENT. +.PP +OID is an object identifier which uniquely +identifies the object type within a MIB. Multiple +OIDs can be specified on a single snmpdelta command. +.PP +.SH OPTIONS +.TP 8 +.B COMMON OPTIONS +Please see +.I snmpcmd(1) +for a list of possible values for COMMON OPTIONS +as well as their descriptions. +.TP +.B \-Cf +Don't fix errors and retry the request. +Without this option, if multiple oids have been specified for +a single request and if the request for one or more of the +oids fails, snmpdelta will retry the request so that data for +oids apart from the ones that failed will still be returned. +Specifying \-Cf tells +.I snmpdelta +not to retry a request, even +if there are multiple oids specified. +.TP +.B \-Ct +Flag will determine time interval from the monitored entity. +.TP +.B \-Cs +Flag will display a timestamp. +.TP +.B \-CS +Generates a "sum count" in addition to the individual instance +counts. The "sum count" is the total of all the individual +deltas for each time period. +.TP +.B \-Cm +Prints the max value ever attained. +.TP +.B \-CF configfile +Tells +.B snmpdelta +to read it's configuration from the specified file. +This options allows the input to be set up in advance rather +than having to be specified on the command line. +.TP +.B \-Cl +Tells +.B snmpdelta +to write it's configuration to files whose names correspond to the MIB +instances monitored. For example, snmpdelta \-Cl localhost ifInOctets.1 +will create a file "localhost\-ifInOctets.1". +.TP +.B \-Cp +Specifies the number of seconds between polling periods. +Polling constitutes sending a request to the agent. The +default polling period is one second. +.TP +.B \-CP peaks +Specifies the reporting period in number of polling periods. +If this option is specified, snmpdelta polls the agent +.I peaks +number of times before reporting the results. +The result reported includes the average value over +the reporting period. In addition, the highest polled +value within the reporting period is shown. +.TP +.B \-Ck +When the polling period (\-Cp) is an increment of 60 seconds +and the timestamp is displayed in the output (\-Cs), then +the default display shows the timestamp in the format +hh:mm mm/dd. This option causes the timestamp format +to be hh:mm:ss mm/dd. +.TP +.B \-CT +Makes +.B snmpdelta +print its output in tabular form. +.TP +.B \-Cv vars/pkt +Specifies the maximum number of oids allowed to be packaged +in a single PDU. Multiple PDUs can be created in a single +request. The default value of variables per packet is 60. +This option is useful if a request response results in an +error becaues the packet is too big. +.PP +Note that +.B snmpdelta +REQUIRES an argument specifying the agent to query +and at least one OID argument, as described in the +.I snmpcmd(1) +manual page. +.SH EXAMPLES +.nf +$ snmpdelta \-c public \-v 1 \-Cs localhost IF\-MIB::ifInUcastPkts.3 IF\-MIB::ifOutUcastPkts.3 +[20:15:43 6/14] ifInUcastPkts.3 /1 sec: 158 +[20:15:43 6/14] ifOutUcastPkts.3 /1 sec: 158 +[20:15:44 6/14] ifInUcastPkts.3 /1 sec: 184 +[20:15:44 6/14] ifOutUcastPkts.3 /1 sec: 184 +[20:15:45 6/14] ifInUcastPkts.3 /1 sec: 184 +[20:15:45 6/14] ifOutUcastPkts.3 /1 sec: 184 +[20:15:46 6/14] ifInUcastPkts.3 /1 sec: 158 +[20:15:46 6/14] ifOutUcastPkts.3 /1 sec: 158 +[20:15:47 6/14] ifInUcastPkts.3 /1 sec: 184 +[20:15:47 6/14] ifOutUcastPkts.3 /1 sec: 184 +[20:15:48 6/14] ifInUcastPkts.3 /1 sec: 184 +[20:15:48 6/14] ifOutUcastPkts.3 /1 sec: 184 +[20:15:49 6/14] ifInUcastPkts.3 /1 sec: 158 +[20:15:49 6/14] ifOutUcastPkts.3 /1 sec: 158 +^C +$ snmpdelta \-c public \-v 1 \-Cs \-CT localhost IF\-MIB:ifInUcastPkts.3 IF\-MIB:ifOutcastPkts.3 +localhost ifInUcastPkts.3 ifOutUcastPkts.3 +[20:15:59 6/14] 184.00 184.00 +[20:16:00 6/14] 158.00 158.00 +[20:16:01 6/14] 184.00 184.00 +[20:16:02 6/14] 184.00 184.00 +[20:16:03 6/14] 158.00 158.00 +[20:16:04 6/14] 184.00 184.00 +[20:16:05 6/14] 184.00 184.00 +[20:16:06 6/14] 158.00 158.00 +^C +.fi +.PP +The following example uses a number of options. Since the +.I Cl +option is specified, the output is sent to a file and not to the +screen. +.PP +.nf +$ snmpdelta \-c public \-v 1 \-Ct \-Cs \-CS \-Cm \-Cl \-Cp 60 \-CP 60 + interlink.sw.net.cmu.edu .1.3.6.1.2.1.2.2.1.16.3 .1.3.6.1.2.1.2.2.1.16.4 +.fi +.SH "SEE ALSO" +snmpcmd(1), variables(5). diff --git a/man/snmpdf.1.def b/man/snmpdf.1.def new file mode 100644 index 0000000..75ebaf8 --- /dev/null +++ b/man/snmpdf.1.def @@ -0,0 +1,71 @@ +.\" Portions of this file are subject to the following copyright. See +.\" the Net-SNMP's COPYING file for more details and other copyrights +.\" that may apply: +.\" /*********************************************************** +.\" Portions of this file are copyrighted by: +.\" Copyright Copyright 2003 Sun Microsystems, Inc. All rights reserved. +.\" Use is subject to license terms specified in the COPYING file +.\" distributed with the Net-SNMP package. +.\" ******************************************************************/ +.TH SNMPDF 1 "25 Jul 2003" VVERSIONINFO "Net-SNMP" +.SH NAME +snmpdf - display disk space usage on a network entity via SNMP +.SH SYNOPSIS +.B snmpdf +[COMMON OPTIONS] [\-Cu] AGENT +.SH DESCRIPTION +.B snmpdf +is simply a networked version of the typical df command. It +checks the disk space on the remote machine by examining the +HOST\-RESOURCES\-MIB's hrStorageTable or the UCD\-SNMP\-MIB's dskTable. +By default, the hrStorageTable is preferred as it typically contains +more information. However, the \-Cu argument can be passed to snmpdf +to force the usage of the dskTable. +.PP +AGENT identifies a target SNMP agent, which is instrumented +to monitor the gievn objects. At its simplest, the AGENT +specification will consist of a hostname or an IPv4 +address. In this situation, the command will attempt +communication with the agent, using UDP/IPv4 to port 161 +of the given target host. See the +.I snmpcmd(1) +manual page for a full list of the possible formats for AGENT. +.PP +See the +.I snmpd.conf(5) +manual page on setting up the dskTable using the +.I disk +directive in the snmpd.conf file. +.SH "OPTIONS" +.TP 8 +.B COMMON OPTIONS +Please see +.I snmpcmd(1) +for a list of possible values for COMMON OPTIONS +as well as their descriptions. +.TP +.B \-Cu +Forces the command to use dskTable in mib +UCD\-SNMP\-MIB instead of the default to determine +the storage information. Generally, the default +use of hrStorageTable in mib HOST\-RESOURCES\-MIB +is preferred because it typically contains +more information. +.SH "EXAMPLES" +.PP +% snmpdf \-v 2c \-c public localhost +.PP +.nf +Description size (kB) Used Available Used% +/ 7524587 2186910 5337677 29% +/proc 0 0 0 0% +/etc/mnttab 0 0 0 0% +/var/run 1223088 32 1223056 0% +/tmp 1289904 66848 1223056 5% +/cache 124330 2416 121914 1% +/vol 0 0 0 0% +Real Memory 524288 447456 76832 85% +Swap Space 1420296 195192 1225104 13% +.fi +.SH "SEE ALSO" +snmpd.conf(5), snmp.conf(5) diff --git a/man/snmpget.1.def b/man/snmpget.1.def new file mode 100644 index 0000000..0ecac19 --- /dev/null +++ b/man/snmpget.1.def @@ -0,0 +1,118 @@ +.\" -*- nroff -*- +.\" Portions of this file are subject to the following copyright. See +.\" the Net-SNMP COPYING file for more details and other copyrights +.\" that may apply: +.\" /*********************************************************** +.\" Copyright 1988, 1989 by Carnegie Mellon University +.\" +.\" All Rights Reserved +.\" +.\" Permission to use, copy, modify, and distribute this software and its +.\" documentation for any purpose and without fee is hereby granted, +.\" provided that the above copyright notice appear in all copies and that +.\" both that copyright notice and this permission notice appear in +.\" supporting documentation, and that the name of CMU not be +.\" used in advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" +.\" CMU DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING +.\" ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL +.\" CMU BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR +.\" ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, +.\" WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, +.\" ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS +.\" SOFTWARE. +.\" ******************************************************************/ +.TH SNMPGET 1 "18 Jun 2007" VVERSIONINFO "Net-SNMP" +.SH NAME +snmpget - communicates with a network entity using SNMP GET requests +.SH SYNOPSIS +.B snmpget +[COMMON OPTIONS] [\-Cf] AGENT OID [OID]... +.SH DESCRIPTION +.B snmpget +is an SNMP application that uses the SNMP GET request to query for +information on a network entity. One or more object identifiers +(OIDs) may be given as arguments on the command line. Each variable +name is given in the format specified in +.IR variables(5) . +.SH "OPTIONS" +.TP 8 +.B \-Cf +If +.B \-Cf +is +.I not +specified, some applications +.RB ( snmpdelta ", " snmpget ", " snmpgetnext " and " snmpstatus ) +will try to fix errors returned by the agent that you were talking to +and resend the request. The only time this is really useful is if you +specified a OID that didn't exist in your request and you're using +SNMPv1 which requires "all or nothing" kinds of requests. +.PP +In addition to this option, +.B snmpget +takes the common options described in the +.I snmpcmd(1) +manual page. +Note that +.B snmpget +REQUIRES an argument specifying the agent to query +and at least one OID argument, as described there. +.SH "EXAMPLES" +The command: +.PP + snmpget \-c public zeus system.sysDescr.0 +.PP +will retrieve the variable system.sysDescr.0 from the host +.B zeus +using the community string +.B public +: +.PP + system.sysDescr.0 = "SunOS zeus.net.cmu.edu 4.1.3_U1 1 sun4m" +.PP +If the network entity has an error processing the request packet, an +error packet will be returned and a message will be shown, helping to +pinpoint in what way the request was malformed. If there were other +variables in the request, the request will be resent without the bad +variable. +.PP +Here is another example. The \-c and \-v options are defined in the +.I snmpcmd(1) +manual page. (Note that system.sysUpTime is an incomplete +OID, as it needs the .0 index appended to it): +.PP +.nf + snmpget \-v1 \-Cf \-c public localhost system.sysUpTime system.sysContact.0 +.fi +.PP +This example will return the following: +.PP +.nf + Error in packet + Reason: (noSuchName) There is no such variable name in this MIB. + This name doesn't exist: system.sysUpTime +.fi +.PP +Similarly, the command: +.nf + snmpget \-v1 \-c public localhost system.sysUpTime system.sysContact.0 +.fi +.PP +Will return: +.PP +.nf + Error in packet + Reason: (noSuchName) There is no such variable name in this MIB. + This name doesn't exist: system.sysUpTime + + system.sysContact.0 = STRING: root@localhost +.fi +.PP +With the +.B +\-Cf +flag specified the application will not try to fix the PDU for you. +.SH "SEE ALSO" +snmpcmd(1), snmpwalk(1), variables(5). diff --git a/man/snmpgetnext.1.def b/man/snmpgetnext.1.def new file mode 100644 index 0000000..5e99a18 --- /dev/null +++ b/man/snmpgetnext.1.def @@ -0,0 +1,77 @@ +.\" -*- nroff -*- +.\" Portions of this file are subject to the following copyright. See +.\" the Net-SNMP COPYING file for more details and other copyrights +.\" that may apply: +.\" /*********************************************************** +.\" Copyright 1988, 1989 by Carnegie Mellon University +.\" +.\" All Rights Reserved +.\" +.\" Permission to use, copy, modify, and distribute this software and its +.\" documentation for any purpose and without fee is hereby granted, +.\" provided that the above copyright notice appear in all copies and that +.\" both that copyright notice and this permission notice appear in +.\" supporting documentation, and that the name of CMU not be +.\" used in advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" +.\" CMU DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING +.\" ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL +.\" CMU BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR +.\" ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, +.\" WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, +.\" ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS +.\" SOFTWARE. +.\" ******************************************************************/ +.TH SNMPGETNEXT 1 "04 Mar 2002" VVERSIONINFO "Net-SNMP" +.SH NAME +snmpgetnext - communicates with a network entity using SNMP GETNEXT requests +.SH SYNOPSIS +.B snmpgetnext +[COMMON OPTIONS] [\-Cf] AGENT OID [OID]... +.SH DESCRIPTION +.B snmpget +is an SNMP application that uses the SNMP GETNEXT request to query for +information on a network entity. One or more object identifiers +(OIDs) may be given as arguments on the command line. Each variable +name is given in the format specified in +.IR variables(5) . +For each one, the variable that is lexicographically "next" in the +remote entity's MIB will be returned. +.PP +For example: +.PP +snmpgetnext \-c public zeus interfaces.ifTable.ifEntry.ifType.1 +.PP +will retrieve the variable interfaces.ifTable.ifEntry.ifType.2: +.PP +interfaces.ifTable.ifEntry.ifType.2 = softwareLoopback(24) +.PP +If the network entity has an error processing the request packet, an +error message will be shown, helping to pinpoint in what way the +request was malformed. +.SH "OPTIONS" +.TP 8 +.B \-Cf +If +.B \-Cf +is +.I not +specified, some applications +.RB ( snmpdelta ", " snmpget ", " snmpgetnext " and " snmpstatus ) +will try to fix errors returned by the agent that you were talking to +and resend the request. The only time this is really useful is if you +specified a OID that didn't exist in your request and you're using +SNMPv1 which requires "all or nothing" kinds of requests. +.PP +In addition to this option, +.B snmpgetnext +takes the common options described in the +.I snmpcmd(1) +manual page. +Note that +.B snmpgetnext +REQUIRES an argument specifying the agent to query +and at least one OID argument, as described there. +.SH "SEE ALSO" +snmpcmd(1), snmpget(1), variables(5). diff --git a/man/snmpinform.1 b/man/snmpinform.1 new file mode 100644 index 0000000..6734e85 --- /dev/null +++ b/man/snmpinform.1 @@ -0,0 +1 @@ +.so man1/snmptrap.1 diff --git a/man/snmpnetstat.1.def b/man/snmpnetstat.1.def new file mode 100644 index 0000000..e3aa634 --- /dev/null +++ b/man/snmpnetstat.1.def @@ -0,0 +1,314 @@ +.\" Portions of this file are subject to the following copyright. See +.\" the Net-SNMP's COPYING file for more details and other copyrights +.\" that may apply: +.\" /*********************************************************** +.\" Copyright 1989 by Carnegie Mellon University +.\" +.\" All Rights Reserved +.\" +.\" Permission to use, copy, modify, and distribute this software and its +.\" documentation for any purpose and without fee is hereby granted, +.\" provided that the above copyright notice appear in all copies and that +.\" both that copyright notice and this permission notice appear in +.\" supporting documentation, and that the name of CMU not be +.\" used in advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" +.\" CMU DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING +.\" ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL +.\" CMU BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR +.\" ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, +.\" WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, +.\" ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS +.\" SOFTWARE. +.\" ******************************************************************/ +.\" +.\" Copyright (c) 1983, 1988, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)netstat.1 6.8 (Berkeley) 9/20/88 +.\" +.\" /*********************************************************** +.\" Portions of this file are copyrighted by: +.\" Copyright Copyright 2003 Sun Microsystems, Inc. All rights reserved. +.\" Use is subject to license terms specified in the COPYING file +.\" distributed with the Net-SNMP package. +.\" ******************************************************************/ +.TH SNMPNETSTAT 1 "20 Jan 2010" VVERSIONINFO "Net-SNMP" +.SH NAME +snmpnetstat \- display networking status and configuration information from a network entity via SNMP +.SH SYNOPSIS +.B snmpnetstat +[COMMON OPTIONS] [\-Ca] [\-Cn] AGENT +.br +.B snmpnetstat +[COMMON OPTIONS] [\-Ci] [\-Co] [\-Cr] [\-Cn] [\-Cs] AGENT +.br +.B snmpnetstat +[COMMON OPTIONS] [\-Ci] [\-Cn] [\-CI interface] AGENT [interval] +.br +.B snmpnetstat +[COMMON OPTIONS] [\-Ca] [\-Cn] [\-Cs] [\-Cp protocol] AGENT +.SH DESCRIPTION +The +.B snmpnetstat +command symbolically displays the values of various network-related +information retrieved from a remote system using the SNMP protocol. +There are a number of output formats, +depending on the options for the information presented. +The first form of the command displays a list of active sockets. +The second form presents the values of other network-related +information according to the option selected. +Using the third form, with an +.I interval +specified, +.I snmpnetstat +will continuously display the information regarding packet +traffic on the configured network interfaces. +The fourth form displays statistics about the named protocol. +.PP +.B snmpnetstat +will issue GETBULK requests to query for information +if at least protocol version +.I v2 +is used. +.PP +AGENT identifies a target SNMP agent, which is +instrumented to monitor the given objects. +At its simplest, the AGENT specification will +consist of a hostname or an IPv4 address. In this +situation, the command will attempt communication +with the agent, using UDP/IPv4 to port 161 of the +given target host. See snmpcmd(1) for a full list of +the possible formats for AGENT. +.PP +.SH OPTIONS +The options have the following meaning: +.PP +.B COMMON OPTIONS + Please see +.I snmpcmd(1) +for a list of possible values for common options +as well as their descriptions. +.PP +.B \-Ca +With the default display, +show the state of all sockets; normally sockets used by +server processes are not shown. +.PP +.B \-Ci +Show the state of all of the network interfaces. +The interface display provides a table of cumulative +statistics regarding packets transferred, errors, and collisions. +The network addresses of the interface and the maximum transmission +unit (``mtu'') are also displayed. +.PP +.B \-Co +Show an abbreviated interface status, giving octets in place of packets. +This is useful when enquiring virtual interfaces (such as Frame-Relay circuits) +on a router. +.PP +.BI \-CI " interface" +Show information only about this interface; +used with an +.I interval +as described below. +.PP +.B \-Cn +Show network addresses as numbers (normally +.I snmpnetstat +interprets addresses and attempts to display them +symbolically). +This option may be used with any of the display formats. +.PP +.BI \-Cp " protocol" +Show statistics about +.IR protocol, +which is either a well-known name for a protocol or an alias for it. Some +protocol names and aliases are listed in the file +.IR /etc/protocols . +A null response typically means that there are no interesting numbers to +report. +The program will complain if +.I protocol +is unknown or if there is no statistics routine for it. +.PP +.B \-Cs +Show per-protocol statistics. When used with the +.B \-Cr +option, show routing statistics instead. +.PP +.B \-Cr +Show the routing tables. +When +.B \-Cs +is also present, show per-protocol routing statistics instead of +the routing tables. +.PP +.BI \-CR " repeaters" +For GETBULK requests, +.I repeaters +specifies the max-repeaters value to use. +.PP +When snmpnetstat is invoked with an interval argument, it +displays a running count of statistics related to network +interfaces. +.I interval +is the number of seconds between +reporting of statistics. +.PP +.I The Active Sockets Display (default) +.PP +The default display, for active sockets, shows the local +and remote addresses, protocol, and the internal state of +the protocol. Address formats are of the form +``host.port'' or ``network.port'' if a socket's address +specifies a network but no specific host address. When +known, the host and network addresses are displayed symbolically +according to the data bases +.I /etc/hosts and +.IR /etc/networks, +respectively. If a symbolic name for an +address is unknown, or if the +.B \-Cn +option is specified, the +address is printed numerically, according to the address +family. For more information regarding the Internet ``dot +format,'' refer to +.IR inet(3N). +Unspecified, or ``wildcard'', addresses and ports appear as ``*''. +.PP +.I The Interface Display +.PP +The interface display provides a table of cumulative +statistics regarding packets transferred, errors, and col- +lisions. The network addresses of the interface and the +maximum transmission unit (``mtu'') are also displayed. +.PP +.I The Routing Table Display +.PP +The routing table display indicates the available routes +and their status. Each route consists of a destination +host or network and a gateway to use in forwarding pack- +ets. The flags field shows the state of the route (``U'' +if ``up''), whether the route is to a gateway (``G''), +whether the route was created dynamically by a redirect +(``D''), and whether the route has been modified by a +redirect (``M''). Direct routes are created for each +interface attached to the local host; the gateway field +for such entries shows the address of the outgoing inter- +face. The interface entry indicates the network interface +utilized for the route. +.PP +.I The Interface Display with an Interval +.PP +When +.I snmpnetstat +is invoked with an +.I interval +argument, it +displays a running count of statistics related to network +interfaces. This display consists of a column for the +primary interface and a column summarizing information for +all interfaces. The primary interface may be replaced +with another interface with the +.B \-CI +option. The first line +of each screen of information contains a summary since the +system was last rebooted. Subsequent lines of output show +values accumulated over the preceding interval. +.PP +.I The Active Sockets Display for a +.I Single Protocol +.PP +When a protocol is specified with the +.B \-Cp +option, the +information displayed is similar to that in the +default display for active sockets, except the +display is limited to the given protocol. +.SH EXAMPLES +Example of using snmpnetstat to display active sockets (default): +.PP +% snmpnetstat \-v 2c \-c public \-Ca testhost +.PP +.nf +Active Internet (tcp) Connections (including servers) +Proto Local Address Foreign Address (state) +tcp *.echo *.* LISTEN +tcp *.discard *.* LISTEN +tcp *.daytime *.* LISTEN +tcp *.chargen *.* LISTEN +tcp *.ftp *.* LISTEN +tcp *.telnet *.* LISTEN +tcp *.smtp *.* LISTEN +\&... + +Active Internet (udp) Connections +Proto Local Address +udp *.echo +udp *.discard +udp *.daytime +udp *.chargen +udp *.time +\&... +.fi +.PP +% snmpnetstat \-v 2c \-c public \-Ci testhost +.PP +.nf +Name Mtu Network Address Ipkts Ierrs Opkts Oerrs Queue +eri0 1500 10.6.9/24 testhost 170548881 245601 687976 0 0 +lo0 8232 127 localhost 7530982 0 7530982 0 0 +.fi +.PP +Example of using snmpnetstat to show statistics about a specific protocol: +.PP +.nf +% snmpnetstat \-v 2c \-c public \-Cp tcp testhost + +Active Internet (tcp) Connections +Proto Local Address Foreign Address (state) +tcp *.echo *.* LISTEN +tcp *.discard *.* LISTEN +tcp *.daytime *.* LISTEN +tcp *.chargen *.* LISTEN +tcp *.ftp *.* LISTEN +tcp *.telnet *.* LISTEN +tcp *.smtp *.* LISTEN +\&... +.fi +.SH SEE ALSO +snmpcmd(1), +iostat(1), +vmstat(1), +hosts(5), +networks(5), +protocols(5), +services(5). +.SH BUGS +The notion of errors is ill-defined. diff --git a/man/snmpset.1.def b/man/snmpset.1.def new file mode 100644 index 0000000..b0c4e07 --- /dev/null +++ b/man/snmpset.1.def @@ -0,0 +1,110 @@ +.\" -*- nroff -*- +.\" Portions of this file are subject to the following copyright. See +.\" the Net-SNMP COPYING file for more details and other copyrights +.\" that may apply: +.\" /*********************************************************** +.\" Copyright 1988, 1989 by Carnegie Mellon University +.\" +.\" All Rights Reserved +.\" +.\" Permission to use, copy, modify, and distribute this software and its +.\" documentation for any purpose and without fee is hereby granted, +.\" provided that the above copyright notice appear in all copies and that +.\" both that copyright notice and this permission notice appear in +.\" supporting documentation, and that the name of CMU not be +.\" used in advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" +.\" CMU DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING +.\" ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL +.\" CMU BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR +.\" ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, +.\" WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, +.\" ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS +.\" SOFTWARE. +.\" ******************************************************************/ +.TH SNMPSET 1 "19 Jun 2003" VVERSIONINFO "Net-SNMP" +.SH NAME +snmpset - communicates with a network entity using SNMP SET requests +.SH SYNOPSIS +.B snmpset +[COMMON OPTIONS] AGENT OID TYPE VALUE [OID TYPE VALUE]... +.SH DESCRIPTION +.B snmpset +is an SNMP application that uses the SNMP SET request to set +information on a network entity. One or more object identifiers +(OIDs) must be given as arguments on the command line. A type and a +value to be set must accompany each object identifier. Each variable +name is given in the format specified in +.IR variables(5) . +.PP +The +.I TYPE +is a single character, one of: +.RS +.PD 0 +.TP 3 +.B i +INTEGER +.TP 3 +.B u +UNSIGNED +.TP 3 +.B s +STRING +.TP 3 +.B x +HEX STRING +.TP 3 +.B d +DECIMAL STRING +.TP 3 +.B n +NULLOBJ +.TP 3 +.B o +OBJID +.TP 3 +.B t +TIMETICKS +.TP 3 +.B a +IPADDRESS +.TP 3 +.B b +BITS +.PD +.RE +Most of these will use the obvious corresponding ASN.1 type. +\&'s', 'x', 'd' and 'b' are all different ways of specifying an OCTET STRING +value, and the 'u' unsigned type is also used for handling Gauge32 values. +.PP +If you have the proper MIB file loaded, you can, in most cases, replace the +type with an '=' sign. For an object of type OCTET STRING this will assume +a string like the 's' type notation. For other types it will do "The +Right Thing". +.PP +For example: +.PP +snmpset \-c private \-v 1 test\-hub system.sysContact.0 s dpz@noc.rutgers.edu ip.ipforwarding.0 = 2 +.PP +will set the variables sysContact.0 and ipForwarding.0: +.PP +system.sysContact.0 = STRING: "dpz@noc.rutgers.edu" +.br +ip.ipForwarding.0 = INTEGER: not\-forwarding(2) +.PP +If the network entity has an error processing the request packet, an +error packet will be returned and a message will be shown, helping to +pinpoint in what way the request was malformed. +.SH OPTIONS +.B snmpset +takes the common options described in the +.I snmpcmd(1) +manual page. +Note that +.B snmpset +REQUIRES an argument specifying the agent to query +and at least one set of OID/type/value arguments, as described in there. +.SH "SEE ALSO" +snmpcmd(1), variables(5). diff --git a/man/snmpstatus.1.def b/man/snmpstatus.1.def new file mode 100644 index 0000000..df7824f --- /dev/null +++ b/man/snmpstatus.1.def @@ -0,0 +1,112 @@ +.\" Portions of this file are subject to the following copyright. See +.\" the Net-SNMP's COPYING file for more details and other copyrights +.\" that may apply: +.\" /*********************************************************** +.\" Copyright 1988, 1989 by Carnegie Mellon University +.\" +.\" All Rights Reserved +.\" +.\" Permission to use, copy, modify, and distribute this software and its +.\" documentation for any purpose and without fee is hereby granted, +.\" provided that the above copyright notice appear in all copies and that +.\" both that copyright notice and this permission notice appear in +.\" supporting documentation, and that the name of CMU not be +.\" used in advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" +.\" CMU DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING +.\" ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL +.\" CMU BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR +.\" ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, +.\" WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, +.\" ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS +.\" SOFTWARE. +.\" ******************************************************************/ +.\" Portions of this file are copyrighted by: +.\" Copyright Copyright 2003 Sun Microsystems, Inc. All rights reserved. +.\" Use is subject to license terms specified in the COPYING file +.\" distributed with the Net-SNMP package. +.\" ******************************************************************/ +.TH SNMPSTATUS 1 "25 Jul 2003" VVERSIONINFO "Net-SNMP" +.SH NAME +snmpstatus - retrieves a fixed set of management information from a network entity +.SH SYNOPSIS +.B snmpstatus +[COMMON OPTIONS] [\-Cf] AGENT +.SH DESCRIPTION +.B snmpstatus +is an SNMP application that retrieves several important statistics +from a network entity. +.PP +AGENT identifies a target SNMP agent, which is instrumented +to monitor the given objects. At its simplest, the AGENT +specification will consist of a hostname or an IPv4 address. +n this situation, the command will attempt communication with +the agent, using UDP/IPv4 to port 161 of the given target host. +.PP +See the +.I snmpcmd(1) +manual page for a full list of the possible formats for AGENT. +.PP +The information returned is: +.IP +The IP address of the entity. +.br +A textual description of the entity (sysDescr.0) +.br +The uptime of the entity's SNMP agent (sysUpTime.0) +.br +The sum of received packets on all interfaces +(ifInUCastPkts.* + ifInNUCastPkts.*) +.br +The sum of transmitted packets on all interfaces +(ifOutUCastPkts.* + ifOutNUCastPkts.*) +.br +The number of IP input packets (ipInReceives.0) +.br +The number of IP output packets (ipOutRequests.0) +.PP +For example: +.PP +snmpstatus \-c public \-v 1 netdev\-kbox.cc.cmu.edu +.PP +will produce output similar to the following: +.PP +[128.2.56.220]=>[Kinetics FastPath2] Up: 1 day, 4:43:31 +.br +Interfaces: 1, Recv/Trans packets: 262874/39867 | +IP: 31603/15805 +.PP +.B snmpstatus +also checks the operational status of all interfaces (ifOperStatus.*), +and if it finds any that are not running, it will report in a manner +similar to this: +.PP +2 interfaces are down! +.PP +If the network entity has an error processing the request packet, an +error packet will be returned and a message will be shown, helping to +pinpoint in what way the request was malformed. +.B snmpstatus +will attempt to reform its request to eliminate the malformed +variable (unless the +.B \-Cf +option is given, see below), but this variable will then be missing +from the displayed data. +.PP +.SH OPTIONS +.TP +.B COMMON OPTIONS +Please see +.I snmpcmd(1) +for a list of possible values for COMMON OPTIONS +as well as their descriptions. +.TP +.B \-Cf +By default, snmpstatus will try to fix errors returned +by the agent and retry a request. In this situation, +the command will display the data that it can. If the \-Cf option +is specified, then snmpstatus will not try to fix +errors, and the error will cause the command to terminate. +.SH "SEE ALSO" +snmpcmd(1), snmpget(1) diff --git a/man/snmptable.1.def b/man/snmptable.1.def new file mode 100644 index 0000000..743da1b --- /dev/null +++ b/man/snmptable.1.def @@ -0,0 +1,167 @@ +.\" /************************************************************ +.\" Copyright 1997 Niels Baggesen +.\" +.\" All Rights Reserved +.\" +.\" Permission to use, copy, modify, and distribute this software and its +.\" documentation for any purpose and without fee is hereby granted, +.\" provided that the above copyright notice appear in all copies. +.\" +.\" I DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING +.\" ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL +.\" I BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR +.\" ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, +.\" WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, +.\" ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS +.\" SOFTWARE. +.\" ******************************************************************/ +.\" Portions of this file are copyrighted by: +.\" Copyright Copyright 2003 Sun Microsystems, Inc. All rights reserved. +.\" Use is subject to license terms specified in the COPYING file +.\" distributed with the Net-SNMP package. +.\" ******************************************************************/ +.TH SNMPTABLE 1 "25 Jul 2003" VVERSIONINFO "Net-SNMP" +.SH NAME +snmptable - retrieve an SNMP table and display it in tabular form +.SH SYNOPSIS +.B snmptable +[COMMON OPTIONS] [\-Cb] [\-CB] [\-Ch] [\-CH] [\-Ci] [\-Cf STRING] [\-Cw WIDTH] +AGENT TABLE\-OID +.SH DESCRIPTION +.B snmptable +is an SNMP application that repeatedly uses the SNMP GETNEXT or +GETBULK requests to query for information on a network entity. The +parameter +.I TABLE\-OID +must specify an SNMP table. +.PP +snmptable is an SNMP application that repeatedly uses the +SNMP GETNEXT or GETBULK requests to query for information +on a network entity. The parameter TABLE\-OID must specify +an SNMP table. + +AGENT identifies a target SNMP agent, which is instrumented +to monitor the gievn objects. At its simplest, the AGENT +specification will consist of a hostname or an IPv4 +address. In this situation, the command will attempt +communication with the agent, using UDP/IPv4 to port 161 +of the given target host. See +.I snmpcmd(1) +for a full list of +the possible formats for AGENT. +.SH OPTIONS +.TP 8 +.B COMMON OPTIONS +Please see +.I snmpcmd(1) +for a list of possible values for COMMON OPTIONS +as well as their descriptions. +.TP +.B \-Cb +Display only a brief heading. Any common prefix of the table field +names will be deleted. +.TP +.B \-CB +Do not use GETBULK requests to retrieve data, only GETNEXT. +.TP +.BI \-Cc " CHARS" +Print table in columns of +.I CHARS +characters width. +.TP +.BI \-Cf " STRING" +The string +.I STRING +is used to separate table columns. With this option, each table entry +will be printed in compact form, just with the string given to +separate the columns (useful if you want to import it into a +database). Otherwise it is printed in nicely aligned columns. +.TP +.B \-Ch +Display +.I only +the column headings. +.TP +.B \-CH +Do not display the column headings. +.TP +.B \-Ci +This option prepends the index of the entry to all printed lines. +.TP +.B \-Cl +Left justify the data in each column. +.TP +.BI \-Cr " REPEATERS" +For GETBULK requests, +.I REPEATERS +specifies the max-repeaters value to use. For GETNEXT requests, +.I REPEATERS +specifies the number of entries to retrieve at a time. +.TP +.BI \-Cw " WIDTH" +Specifies the width of the lines when the table is printed. +If the lines will be longer, the table will be printed in sections of +at most +.I WIDTH +characters. If +.I WIDTH +is less than the length of the contents of +a single column, then that single column will still be printed. +.PP +Note that +.B snmptable +REQUIRES an argument specifying the agent to query +and exactly one OID argument, as described in the +.I snmpcmd(1) +manual page. This OID \fBmust\fP be that of a MIB table object. +.SH EXAMPLES +$ snmptable \-v 2c \-c public localhost at.atTable + +SNMP table: at.atTable RFC1213\-MIB::atTable + +atIfIndex atPhysAddress atNetAddress + 1 8:0:20:20:0:ab 130.225.243.33 +.PP +$ snmptable \-v 2c \-c public \-Cf + localhost at.atTable + +SNMP table: at.atTable + +atIfIndex+atPhysAddress+atNetAddress +1+8:0:20:20:0:ab+130.225.243.33 +.PP +.nf +$ snmptable localhost \-Cl \-CB \-Ci \-OX \-Cb \-Cc 16 \-Cw 64 ifTable + +SNMP table: ifTable + +Index Descr Type Mtu +Speed PhysAddress AdminStatus OperStatus +LastChange InOctets InUcastPkts InNUcastPkts +InDiscards InErrors InUnknownProtos OutOctets +OutUcastPkts OutNUcastPkts OutDiscards OutErrors +OutQLen Specific + +index: [1] +1 lo softwareLoopbac 16436 +10000000 up up +? 2837283786 3052466 ? +0 0 ? 2837283786 +3052466 ? 0 0 +0 zeroDotZero + +index: [2] +2 eth0 ethernetCsmacd 1500 +10000000 0:5:5d:d1:f7:cf up up +? 2052604234 44252973 ? +0 0 ? 149778187 +65897282 ? 0 0 +0 zeroDotZero +.PP +.SH "BUGS" +The test for +.I TABLE\-OID +actually specifying a table is rather heuristic. Note also that the +test requires the defining MIB file to be loaded. +.PP +.SH "SEE ALSO" +snmpcmd(1), variables(5). diff --git a/man/snmptest.1.def b/man/snmptest.1.def new file mode 100644 index 0000000..7874196 --- /dev/null +++ b/man/snmptest.1.def @@ -0,0 +1,278 @@ +.\" Portions of this file are subject to the following copyright. See +.\" the Net-SNMP's COPYING file for more details and other copyrights +.\" that may apply: +.\" /*********************************************************** +.\" Copyright 1988, 1989 by Carnegie Mellon University +.\" +.\" All Rights Reserved +.\" +.\" Permission to use, copy, modify, and distribute this software and its +.\" documentation for any purpose and without fee is hereby granted, +.\" provided that the above copyright notice appear in all copies and that +.\" both that copyright notice and this permission notice appear in +.\" supporting documentation, and that the name of CMU not be +.\" used in advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" +.\" CMU DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING +.\" ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL +.\" CMU BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR +.\" ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, +.\" WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, +.\" ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS +.\" SOFTWARE. +.\" ******************************************************************/ +.\" Portions of this file are copyrighted by: +.\" Copyright Copyright 2003 Sun Microsystems, Inc. All rights reserved. +.\" Use is subject to license terms specified in the COPYING file +.\" distributed with the Net-SNMP package. +.\" ******************************************************************/ +.TH SNMPTEST 1 "25 Jul 2003" VVERSIONINFO "Net-SNMP" +.SH NAME +snmptest - communicates with a network entity using SNMP requests +.SH SYNOPSIS +.B snmptest +[COMMON OPTIONS] AGENT +.SH DESCRIPTION +.B snmptest +is a flexible SNMP application that can monitor and manage information +on a network entity. +.PP +After invoking the program, a command line interpreter proceeds to +accept commands. This intepreter enables the user to send different +types of SNMP requests to target agents. +.PP +AGENT identifies a target SNMP agent, which is instrumented +to monitor the given objects. At its simplest, the AGENT +specification will consist of a hostname or an IPv4 +address. In this situation, the command will attempt +communication with the agent, using UDP/IPv4 to port 161 +of the given target host. See snmpcmd(1) for a full list of +the possible formats for AGENT. +.PP +Once snmptest is invoked, the command line intepreter will prompt with: +.PP +.B Variable: +.PP +At this point you can enter one or more variable names, one per line. +A blank line ends the parameter input and will send the request +(variables entered) in a single packet, to the remote entity. +Each variable name is given +in the format specified in +.IR variables(5) . +For example: +.PP +snmptest \-c public \-v 1 zeus +.br +.BR Variable: " system.sysDescr.0" +.br +.BR Variable: +.PP +will return some information about the request and reply packets, as +well as the information: +.PP +requestid 0x5992478A errstat 0x0 errindex 0x0 +.br +system.sysDescr.0 = STRING: "Unix 4.3BSD" +.PP +The errstatus value shows the error status code for the call. +The possible values for errstat are in the header file snmp.h. +The errindex value identifies the variable that has the given error. +Index values are assigned to all the variables entered at the "Variable": +prompt. The first value is assigned an index of 1. +.PP +Upon startup, the program defaults to sending a GET request packet. +The type of request can be changed by typing one of the following +commands at the "Variable:" prompt: +.PP +.nf +$G - send a GET request +$N - send a GETNEXT request +$S - send a SET request +$B - send a GETBULK request + Note: GETBULK is not available in SNMPv1 +$I - send an Inform request +$T - send an SNMPv2 Trap request +.fi +.PP +Other values that can be entered at the "Variable:" prompt are: +.PP +.nf +$D - toggle the dumping of each sent and received packet +$QP - toggle a quicker, less verbose output form +$Q - Quit the program +.fi +.PP +Request Types: +.PP +GET Request: +.PP +When in "GET request" mode ($G or default), the user can enter +an OID at the "Variable:" prompt. The user can enter multiple +OIDs, one per prompt. The user enters a blank line to send +the GET request. +.PP +GETNEXT Request: +.PP +The "GETNEXT request" mode ($N) is simlar to the "Get request" +mode, described above. +.PP +SET Request: +.PP +When in the "SET request" mode ($S), more information is requested by the +prompt for each variable. The prompt: +.PP +.nf +Type [i|s|x|d|n|o|t|a]: +.fi +requests the type of the variable be entered. Depending on the type +of value you want to set, you can type one of the following: +.PP +.nf +i - integer +u - unsigned integer +s - octet string in ASCII +x - octet string in hex bytes, separated by whitespace +d - octet string as decimal bytes, separated by whitespace +a - ip address in dotted IP notation +o - object identifier +n - null +t - timeticks +.fi +At this point a value will be prompted for: +.PP +Value: +.PP +If this is an integer value, just type the integer (in decimal). If +it is a decimal string, type in white-space separated decimal numbers, +one per byte of the string. Again type a blank line at the prompt for +the variable name to send the packet. +.PP +GETBULK Request: +.PP +The "GETBULK request" mode ($B) is similar to the "Set request" mode. +GETBULK, however, is not available in SNMPv1. +.PP +Inform Request: +.PP +The "Inform request" mode ($I) is similar to the "Set request" mode. +This type of request, however, is not available in SNMPv1. Also, +the _agent_ specified on the snmptest command should correspond +to the target snmptrapd agent. +.PP +SNMPv2 Trap Request: +.PP +The "SNMPv2 Trap Request" mode ($T) is similar to the "Set request" mode. +This type of request, however, is not available in SNMPv1. Also, +the _agent_ specified on the snmptest command should correspond +to the target snmptrapd agent. +.SH OPTIONS +.B snmptest +takes the common options described in the +.I snmpcmd(1) +manual page. +.SH EXAMPLES +.PP +The following is an example of sending a GET request for two OIDs: +.PP +% snmptest \-v 2c \-c public testhost:9999 +.PP +.nf +Variable: system.sysDescr.0 +Variable: system.sysContact.0 +Variable: +Received Get Response from 128.2.56.220 +requestid 0x7D9FCD63 errstat 0x0 errindex 0x0 +SNMPv2\-MIB::sysDescr.0 = STRING: SunOS testhost 5.9 Generic_112233\-02 sun4u +SNMPv2\-MIB::sysContact.0 = STRING: x1111 +.fi +.PP +The following is an example of sending a GETNEXT request: +.PP +.nf +Variable: SNMPv2\-MIB::sysORUpTime +Variable: +Received Get Response from 128.2.56.220 +requestid 0x7D9FCD64 errstat 0x0 errindex 0x0 +SNMPv2\-MIB::sysORUpTime.1 = Timeticks: (6) 0:00:00.06 +Variable: +.fi +.PP +The following is an example of sending a SET request: +.PP +.nf +Variable: $S +Request type is Set Request +Variable: system.sysLocation.0 +Type [i|u|s|x|d|n|o|t|a]: s +Value: building 17 +Variable: +Received Get Response from 128.2.56.220 +requestid 0x7D9FCD65 errstat 0x0 errindex 0x0 +SNMPv2\-MIB::sysLocation.0 = STRING: building A +Variable: +.fi +.PP +The following is an example of sending a GETBULK request: +.PP +.nf +Variable: $B +Request type is Bulk Request +Enter a blank line to terminate the list of non-repeaters +and to begin the repeating variables +Variable: +Now input the repeating variables +Variable: system.sysContact.0 +Variable: system.sysLocation.0 +Variable: +What repeat count? 2 +Received Get Response from 128.2.56.220 +requestid 0x2EA7942A errstat 0x0 errindex 0x0 +SNMPv2\-MIB::sysName.0 = STRING: testhost +SNMPv2\-MIB::sysORLastChange.0 = Timeticks: (58) 0:00:00.58 +SNMPv2\-MIB::sysLocation.0 = STRING: bldg A +SNMPv2\-MIB::sysORID.1 = OID: IF\-MIB::ifMIB +Variable: +.fi +.PP +The following is an example of sending an Inform request: +.PP +.nf +snmptest \-v 2c \-c public snmptrapd_host +Variable: $I +Request type is Inform Request +(Are you sending to the right port?) +Variable: system.sysContact.0 +Type [i|u|sIx|d|n|o|t|a]: s +Value: x12345 +Variable: +Inform Acknowledged +Variable: +.fi +.PP +The snmptrapd_host will show: +.PP +snmptrapd_host [<ip address>]: Trap SNMPv2\-MIB::sysContact.0 = STRING: +x12345 +.PP +The following is an example of sending an SNMPv2 Trap request: +.PP +.nf +snmptest \-v 2c \-c public snmptrapd_host +Variable: $T +Request type is SNMPv2 Trap Request +(Are you sending to the right port?) +Variable: system.sysLocation.0 +Type [i|u|s|x|d|n|o|t|a]: s +Value: building a +Variable: +.fi +.PP +The snmptrapd_host will show: +.PP +.nf +snmptrapd_host [<ip address>]: Trap SNMPv2\-MIB::sys.0 = STRING: +building a +.fi +.SH "SEE ALSO" +snmpcmd(1), snmpget(1), snmpset(1), variables(5) diff --git a/man/snmptranslate.1.def b/man/snmptranslate.1.def new file mode 100644 index 0000000..288218b --- /dev/null +++ b/man/snmptranslate.1.def @@ -0,0 +1,288 @@ +.\" Portions of this file are subject to the following copyright. See +.\" the Net-SNMP's COPYING file for more details and other copyrights +.\" that may apply: +.\" /*********************************************************** +.\" Copyright 1988, 1989 by Carnegie Mellon University +.\" +.\" All Rights Reserved +.\" +.\" Permission to use, copy, modify, and distribute this software and its +.\" documentation for any purpose and without fee is hereby granted, +.\" provided that the above copyright notice appear in all copies and that +.\" both that copyright notice and this permission notice appear in +.\" supporting documentation, and that the name of CMU not be +.\" used in advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" +.\" CMU DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING +.\" ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL +.\" CMU BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR +.\" ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, +.\" WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, +.\" ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS +.\" SOFTWARE. +.\" ******************************************************************/ +.\" Portions of this file are copyrighted by: +.\" Copyright Copyright 2003 Sun Microsystems, Inc. All rights reserved. +.\" Use is subject to license terms specified in the COPYING file +.\" distributed with the Net-SNMP package. +.\" ******************************************************************/ +.TH SNMPTRANSLATE 1 "20 Jul 2010" VVERSIONINFO "Net-SNMP" +.SH NAME +snmptranslate - translate MIB OID names between numeric and textual forms +.SH SYNOPSIS +.B snmptranslate +[OPTIONS] OID [OID]... +.SH DESCRIPTION +.B snmptranslate +is an application that translates one or more SNMP object identifier +values from their symbolic (textual) forms into their numerical forms +(or vice versa). +.PP +OID is either a numeric or textual object identifier. +.SH OPTIONS +.TP 8 +.B \-D\fI[TOKEN[,...]] +Turn on debugging output for the given +.IR "TOKEN" "(s)." +Try +.IR ALL +for extremely verbose output. +.TP +.B \-h +Display a brief usage message and then exit. +.TP +.BI \-m " MIBLIST" +Specifies a colon separated list of MIB modules to load for this +application. This overrides the environment variable MIBS. +.IP +The special keyword +.I ALL +is used to specify all modules in all directories when searching for MIB +files. Every file whose name does not begin with "." will be parsed as +if it were a MIB file. +.TP +.BI \-M " DIRLIST" +Specifies a colon separated list of directories to search for MIBs. +This overrides the environment variable MIBDIRS. +.TP +.BI \-T " TRANSOPTS" +Provides control over the translation of the OID values. The +following +.I TRANSOPTS +are available: +.RS +.TP 6 +.B \-Td +Print full details of the specified OID. +.TP +.B \-Tp +Print a graphical tree, rooted at the specified OID. +.TP +.B \-Ta +Dump the loaded MIB in a trivial form. +.TP +.B \-Tl +Dump a labeled form of all objects. +.TP +.B \-To +Dump a numeric form of all objects. +.TP +.B \-Ts +Dump a symbolic form of all objects. +.TP +.B \-Tt +Dump a tree form of the loaded MIBs (mostly useful for debugging). +.TP +.B \-Tz +Dump a numeric and labeled form of all objects (compatible with MIB2SCHEMA format). +.RE +.TP +.B \-V +Display version information for the application and then exit. +.TP +.BI \-w " WIDTH" +Specifies the width of +.B \-Tp +and +.B \-Td +output. The default is very large. +.PP +In addition to the above options, +.B snmptranslate +takes the OID input +.RB ( \-I ), +MIB parsing +.RB ( \-M ) +and OID output +.RB ( \-O ) +options described in the +.BR "INPUT OPTIONS" ", " "MIB PARSING OPTIONS" " and " "OUTPUT OPTIONS" +sections of the +.I snmpcmd(1) +manual page. +.SH EXAMPLES +.IP \(bu 4 +snmptranslate \-On \-IR sysDescr +.br +will translate "sysDescr" to a more qualified form: +.IP +system.sysDescr +.IP \(bu 4 +snmptranslate \-Onf \-IR sysDescr +.br +will translate "sysDecr" to: +.IP +.RI .iso.org.dod.internet.mgmt.mib\-2.system.sysDescr +.IP \(bu 4 +snmptranslate \-Td \-OS system.sysDescr +.br +will translate "sysDecr" into: +.IP +.nf +SNMPv2\-MIB::sysDescr +sysDescr OBJECT\-TYPE + \-\- FROM SNMPv2\-MIB + \-\- TEXTUAL CONVENTION DisplayString + SYNTAX OCTET STRING (0..255) + DISPLAY\-HINT "255a" + MAX\-ACCESS read\-only + STATUS current + DESCRIPTION "A textual description of the entity. This + value should include the full name and + version identification of the system's + hardware type, software operating\-system, + and networking software." +::= { iso(1) org(3) dod(6) internet(1) mgmt(2) mib\-2(1) system(1) 1 } +.fi +.IP \(bu 4 +snmptranslate \-Tp \-OS system +.br +will print the following tree: +.IP +.nf ++--system(1) + | + +-- -R-- String sysDescr(1) + | Textual Convention: DisplayString + | Size: 0..255 + +-- -R-- ObjID sysObjectID(2) + +-- -R-- TimeTicks sysUpTime(3) + +-- -RW- String sysContact(4) + | Textual Convention: DisplayString + | Size: 0..255 + +-- -RW- String sysName(5) + | Textual Convention: DisplayString + | Size: 0..255 + +-- -RW- String sysLocation(6) + | Textual Convention: DisplayString + | Size: 0..255 + +-- -R-- Integer sysServices(7) + +-- -R-- TimeTicks sysORLastChange(8) + | Textual Convention: TimeStamp + | + +--sysORTable(9) + | + +--sysOREntry(1) + | + +-- ---- Integer sysORIndex(1) + +-- -R-- ObjID sysORID(2) + +-- -R-- String sysORDescr(3) + | Textual Convention: DisplayString + | Size: 0..255 + +-- -R-- TimeTicks sysORUpTime(4) + Textual Convention: TimeStamp + +.fi +.PP +.IP \(bu 4 +snmptranslate \-Ta | head +.br +will produce the following dump: +.IP +.nf +dump DEFINITIONS ::= BEGIN +org ::= { iso 3 } +dod ::= { org 6 } +internet ::= { dod 1 } +directory ::= { internet 1 } +mgmt ::= { internet 2 } +experimental ::= { internet 3 } +private ::= { internet 4 } +security ::= { internet 5 } +snmpV2 ::= { internet 6 } +.fi +.PP +.IP \(bu 4 +snmptranslate \-Tl | head +.br +will produce the following dump: +.IP +.nf +.RI .iso(1).org(3) +.RI .iso(1).org(3).dod(6) +.RI .iso(1).org(3).dod(6).internet(1) +.RI .iso(1).org(3).dod(6).internet(1).directory(1) +.RI .iso(1).org(3).dod(6).internet(1).mgmt(2) +.RI .iso(1).org(3).dod(6).internet(1).mgmt(2).mib\-2(1) +.RI .iso(1).org(3).dod(6).internet(1).mgmt(2).mib\-2(1).system(1) +.RI .iso(1).org(3).dod(6).internet(1).mgmt(2).mib\-2(1).system(1).sysDescr(1) +.RI .iso(1).org(3).dod(6).internet(1).mgmt(2).mib\-2(1).system(1).sysObjectID(2) +.RI .iso(1).org(3).dod(6).internet(1).mgmt(2).mib\-2(1).system(1).sysUpTime(3) +.fi +.PP +.IP \(bu 4 +snmptranslate \-To | head +.br +will produce the following dump +.IP +.nf +.RI .1.3 +.RI .1.3.6 +.RI .1.3.6.1 +.RI .1.3.6.1.1 +.RI .1.3.6.1.2 +.RI .1.3.6.1.2.1 +.RI .1.3.6.1.2.1.1 +.RI .1.3.6.1.2.1.1.1 +.RI .1.3.6.1.2.1.1.2 +.RI .1.3.6.1.2.1.1.3 +.fi +.PP +.IP \(bu 4 +snmptranslate \-Ts | head +.br +will produce the following dump +.IP +.nf +.RI .iso.org +.RI .iso.org.dod +.RI .iso.org.dod.internet +.RI .iso.org.dod.internet.directory +.RI .iso.org.dod.internet.mgmt +.RI .iso.org.dod.internet.mgmt.mib\-2 +.RI .iso.org.dod.internet.mgmt.mib\-2.system +.RI .iso.org.dod.internet.mgmt.mib\-2.system.sysDescr +.RI .iso.org.dod.internet.mgmt.mib\-2.system.sysObjectID +.RI .iso.org.dod.internet.mgmt.mib\-2.system.sysUpTime +.fi +.PP +.IP \(bu 4 +snmptranslate \-Tt | head +.br +will produce the following dump +.IP +.nf + org(3) type=0 + dod(6) type=0 + internet(1) type=0 + directory(1) type=0 + mgmt(2) type=0 + mib\-2(1) type=0 + system(1) type=0 + sysDescr(1) type=2 tc=4 hint=255a + sysObjectID(2) type=1 + sysUpTime(3) type=8 +.fi +.SH "SEE ALSO" +snmpcmd(1), variables(5), RFC 2578-2580. diff --git a/man/snmptrap.1.def b/man/snmptrap.1.def new file mode 100644 index 0000000..55c19d1 --- /dev/null +++ b/man/snmptrap.1.def @@ -0,0 +1,130 @@ +.\" -*- nroff -*- +.\" Portions of this file are subject to the following copyright. See +.\" the Net-SNMP COPYING file for more details and other copyrights +.\" that may apply: +.\" /*********************************************************** +.\" Copyright 1988, 1989 by Carnegie Mellon University +.\" +.\" All Rights Reserved +.\" +.\" Permission to use, copy, modify, and distribute this software and its +.\" documentation for any purpose and without fee is hereby granted, +.\" provided that the above copyright notice appear in all copies and that +.\" both that copyright notice and this permission notice appear in +.\" supporting documentation, and that the name of CMU not be +.\" used in advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" +.\" CMU DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING +.\" ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL +.\" CMU BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR +.\" ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, +.\" WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, +.\" ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS +.\" SOFTWARE. +.\" ******************************************************************/ +.TH SNMPTRAP 1 "19 Jun 2003" VVERSIONINFO "Net-SNMP" +.SH NAME +snmptrap, snmpinform - sends an SNMP notification to a manager +.SH SYNOPSIS +.B snmptrap \-v 1 +[COMMON OPTIONS] AGENT enterprise-oid agent generic-trap specific-trap uptime [OID TYPE VALUE]... +.PP +.B snmptrap \-v [2c|3] +[COMMON OPTIONS] [\-Ci] AGENT uptime trap-oid [OID TYPE VALUE]... +.PP +.B snmpinform \-v [2c|3] +[COMMON OPTIONS] AGENT uptime trap-oid [OID TYPE VALUE]... +.SH DESCRIPTION +.B snmptrap +is an SNMP application that uses the SNMP TRAP operation to send +information to a network manager. One or more object identifiers +(OIDs) can be given as arguments on the command line. A type and a +value must accompany each object identifier. Each variable name is +given in the format specified in +.IR variables(5) . +.PP +When invoked as +.B snmpinform, +or when +.B \-Ci +is added to the command line flags of snmptrap, it sends an +INFORM-PDU, expecting a response from the trap receiver, +retransmitting if required. Otherwise it sends an TRAP-PDU or +TRAP2-PDU. +.PP +If any of the required version 1 parameters, +.IR enterprise-oid , +.IR agent , +and +.I uptime +are specified as empty, it defaults to +.IR "1.3.6.1.4.1.3.1.1 (enterprises.cmu.1.1)" , +.IR hostname , +and +.I host-uptime +respectively. +.PP +The +.I TYPE +is a single character, one of: +.RS +.PD 0 +.TP 3 +.B i +INTEGER +.TP 3 +.B u +UNSIGNED +.TP 3 +.B c +COUNTER32 +.TP 3 +.B s +STRING +.TP 3 +.B x +HEX STRING +.TP 3 +.B d +DECIMAL STRING +.TP 3 +.B n +NULLOBJ +.TP 3 +.B o +OBJID +.TP 3 +.B t +TIMETICKS +.TP 3 +.B a +IPADDRESS +.TP 3 +.B b +BITS +.PD +.RE +which are handled in the same way as the +.B snmpset +command. +.PP +For example: +.PP +snmptrap \-v 1 \-c public manager enterprises.spider test\-hub 3 0 '' interfaces.iftable.ifentry.ifindex.1 i 1 +.PP +will send a generic linkUp trap to manager, for interface 1. +.SH OPTIONS +.B snmptrap +takes the common options described in the +.I snmpcmd(1) +manual page in +addition to the +.B \-Ci +option described above. +Note that +.B snmptrap +REQUIRES an argument specifying the agent to query +as described there. +.SH SEE ALSO +snmpcmd(1), snmpset(1), variables(5). diff --git a/man/snmptrapd.8.def b/man/snmptrapd.8.def new file mode 100644 index 0000000..12421a8 --- /dev/null +++ b/man/snmptrapd.8.def @@ -0,0 +1,320 @@ +.\" -*- nroff -*- +.\" Portions of this file are subject to the following copyright. See +.\" the Net-SNMP COPYING file for more details and other copyrights +.\" that may apply: +.\" /*********************************************************** +.\" Copyright 1989 by Carnegie Mellon University +.\" +.\" All Rights Reserved +.\" +.\" Permission to use, copy, modify, and distribute this software and its +.\" documentation for any purpose and without fee is hereby granted, +.\" provided that the above copyright notice appear in all copies and that +.\" both that copyright notice and this permission notice appear in +.\" supporting documentation, and that the name of CMU not be +.\" used in advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" +.\" CMU DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING +.\" ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL +.\" CMU BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR +.\" ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, +.\" WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, +.\" ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS +.\" SOFTWARE. +.\" ******************************************************************/ +.TH SNMPTRAPD 8 "30 Mar 2011" VVERSIONINFO "Net-SNMP" +.SH NAME +snmptrapd - Receive and log SNMP trap messages. +.SH SYNOPSIS +.BR snmptrapd " [OPTIONS] [LISTENING ADDRESSES]" +.SH DESCRIPTION +.B snmptrapd +is an SNMP application that receives and logs SNMP TRAP and INFORM +messages. +.PP +Note: the default is to listen on UDP port 162 on all IPv4 interfaces. +Since 162 is a privileged port, +.B snmptrapd +must typically be run as root. +.SH OPTIONS +.TP 8 +.B \-a +Ignore authenticationFailure traps. +.TP +.B \-A +Append to the log file rather than truncating it. + +Note that this needs to come \fIbefore\fP any \-Lf options +that it should apply to. +.TP +.BI "\-c" " FILE" +Read +.I FILE +as a configuration file +(or a comma-separated list of configuration files). +.TP +.B \-C +Do not read any configuration files except the one optionally specified by the +.B \-c +option. +.TP +.B \-d +Dump (in hexadecimal) the sent and received SNMP packets. +.TP +.BI \-D[TOKEN[,...]] +Turn on debugging output for the given +.IR "TOKEN" "(s)." +Try +.IR ALL +for extremely verbose output. +.TP +.B \-f +Do not fork() from the calling shell. +.TP +.BI \-F " FORMAT" +When logging to standard output, use the format in the string +.IR FORMAT . +See the section +.B FORMAT SPECIFICATIONS +below for more details. +.TP +.B \-h, \-\-help +Display a brief usage message and then exit. +.TP +.B \-H +Display a list of configuration file directives understood by the +trap daemon and then exit. +.TP +.B \-I \fI[\-]INITLIST +Specifies which modules should (or should not) be initialized +when snmptrapd starts up. If the comma-separated +.I INITLIST +is preceded +with a '\-', it is the list of modules that should \fInot\fR be started. +Otherwise this is the list of the \fIonly\fR modules that should be started. + +To get a list of compiled modules, run snmptrapd with the arguments +.I "\-Dmib_init \-H" +(assuming debugging support has been compiled in). +.TP +.B \-L[efos] +Specify where logging output should be directed (standard error or output, +to a file or via syslog). See LOGGING OPTIONS in \fIsnmpcmd(1)\fR for details. +.TP +.BR \-m " \fIMIBLIST" +Specifies a colon separated list of MIB modules to load for this +application. This overrides the environment variable MIBS. +See \fIsnmpcmd(1)\fR for details. +.TP +.BR \-M " \fIDIRLIST" +Specifies a colon separated list of directories to search for MIBs. +This overrides the environment variable MIBDIRS. +See \fIsnmpcmd(1)\fR for details. +.TP +.BR \-n +Do not attempt to translate source addresses of incoming packets into +hostnames. +.TP +.BI \-p " FILE" +Save the process ID of the trap daemon in +.IR FILE "." +.TP +.BI \-O " [abeEfnqQsStTuUvxX]" +Specifies how MIB objects and other output should be displayed. +See the section +.B OUTPUT OPTIONS +in the +.I snmpcmd(1) +manual page for details. +.TP +.BI \-t +Do not log traps to syslog. This disables logging to syslog. This is +useful if you want the snmptrapd application to +.B only +run traphandle hooks and not to log any traps to any location. +.TP +.B \-v, \-\-version +Print version information for the trap daemon and then exit. +.TP +.B \-x \fIADDRESS +Connect to the AgentX master agent on the specified address, +rather than the default AGENTX_SOCKET. +See \fIsnmpd(8)\fR for details of the format of such addresses. +.TP +.BI \-\- "name"="value" +Allows one to specify any token ("name") supported in the +.I snmptrapd.conf +file and sets its value to "value". Overrides the corresponding token in the +.I snmptrapd.conf +file. See +.I snmptrapd.conf(5) +for the full list of tokens. +.SH FORMAT SPECIFICATIONS +.PP +.B snmptrapd +interprets format strings similarly to +.IR printf(3) . +It understands the following formatting sequences: +.RS 4 +.TP 4 +.B %% +a literal % +.TP +.B %a +the contents of the agent\-addr field of the PDU (v1 TRAPs only) +.TP +.B %A +the hostname corresponding to the contents of the agent\-addr field of +the PDU, if available, otherwise the contents of the agent\-addr field +of the PDU (v1 TRAPs only). +.TP +.B %b +PDU source address (Note: this is not necessarily an IPv4 +address) +.TP +.B %B +PDU source hostname if available, otherwise PDU source address (see +note above) +.TP +.B %h +current hour on the local system +.TP +.B %H +the hour field from the \fCsysUpTime.0\fR varbind +.TP +.B %j +current minute on the local system +.TP +.B %J +the minute field from the \fCsysUpTime.0\fR varbind +.TP +.B %k +current second on the local system +.TP +.B %K +the seconds field from the \fCsysUpTime.0\fR varbind +.TP +.B %l +current day of month on the local system +.TP +.B %L +the day of month field from the \fCsysUpTime.0\fR varbind +.TP +.B %m +current (numeric) month on the local system +.TP +.B %M +the numeric month field from the \fCsysUpTime.0\fR varbind +.TP +.B %N +enterprise string +.TP +.B %q +trap sub-type (numeric, in decimal) +.TP +.B %P +security information from the PDU (community name for v1/v2c, +user and context for v3) +.TP +.B %t +decimal number of seconds since the operating system epoch (as +returned by +.IR time(2) ) +.TP +.B %T +the value of the \fCsysUpTime.0\fR varbind in seconds +.TP +.B %v +list of variable-bindings from the notification payload. +These will be separated by a tab, +or by a comma and a blank if the alternate form is requested +See also %V +.TP +.B %V +specifies the variable-bindings separator. This takes a sequence of +characters, up to the next % (to embed a % in the string, use \\%) +.TP +.B %w +trap type (numeric, in decimal) +.TP +.B %W +trap description +.TP +.B %y +current year on the local system +.TP +.B %Y +the year field from the \fCsysUpTime.0\fR varbind +.RE +.PP +In addition to these values, an optional field +width and precision may also be specified , just as in +.IR printf(3) , +and a flag value. The following flags are supported: +.RS 4 +.TP 4 +.B \- +left justify +.TP +.B 0 +use leading zeros +.TP +.B # +use alternate form +.RE +.PP +The "use alternate form" flag changes the behavior of various format +string sequences: +.IP +Time information will be displayed based on GMT (rather than the local timezone) +.IP +The variable-bindings will be a comma-separated list (rather than a tab-separated one) +.IP +The system uptime will be broken down into a human-meaningful format (rather than being a simple integer) +.SS Examples: +.PP +To get a message like "14:03 TRAP3.1 from humpty.ucd.edu" you +could use something like this: +.PP +.RS +.nf +snmptrapd \-P \-F "%02.2h:%02.2j TRAP%w.%q from %A\en" +.fi +.RE +.PP +If you want the same thing but in GMT rather than local time, use +.PP +.RS +.nf +snmptrapd \-P \-F "%#02.2h:%#02.2j TRAP%w.%q from %A\en" +.fi +.RE +.SH LISTENING ADDRESSES +By default, +.B snmptrapd +listens for incoming SNMP TRAP and INFORM packets on UDP port 162 on +all IPv4 interfaces. However, it is possible to modify this behaviour +by specifying one or more listening addresses as arguments to +.BR snmptrapd . +See the +.I snmpd(8) +manual page for more information about the format of listening +addresses. +.SH NOTIFICATION\-LOG\-MIB SUPPORT +As of net-snmp 5.0, the snmptrapd application supports the +NOTIFICATION\-LOG\-MIB. It does this by opening an AgentX subagent +connection to the master snmpd agent and registering the notification +log tables. As long as the snmpd application is started first, it +will attach itself to it and thus you should be able to view the last +recorded notifications via the nlmLogTable and nlmLogVariableTable. +See the snmptrapd.conf file and the "doNotRetainNotificationLogs" token +for turning +off this support. See the NOTIFICATION\-LOG\-MIB for more details about +the MIB itself. +.SH EXTENSIBILITY AND CONFIGURATION +See the +.I snmptrapd.conf(5) +manual page. +.SH "SEE ALSO" +snmpcmd(1), snmpd(8), printf(3), snmptrapd.conf(5), syslog(8), variables(5) diff --git a/man/snmptrapd.conf.5.def b/man/snmptrapd.conf.5.def new file mode 100644 index 0000000..9242b28 --- /dev/null +++ b/man/snmptrapd.conf.5.def @@ -0,0 +1,266 @@ +.TH SNMPTRAPD.CONF 5 "19 Feb 2009" VVERSIONINFO "Net-SNMP" +.SH NAME +snmptrapd.conf - configuration file for the Net-SNMP notification receiver +.SH DESCRIPTION +The Net-SNMP notification receiver (trap daemon) uses one or more +configuration files to control its operation and how incoming traps +(and INFORM requests) should be processed. +This file (\fBsnmptrapd.conf\fR) can be located in +one of several locations, as described in the +.I snmp_config(5) +manual page. +.SH IMPORTANT +Previously, +.B snmptrapd +would accept all incoming notifications, and log them automatically +(even if no explicit configuration was provided). +Starting with release 5.3, access control checks will be applied to +incoming notifications. If +.B snmptrapd +is run without a suitable configuration file (or equivalent access +control settings), then such traps \fBWILL NOT\fR +be processed. +See the section \fBACCESS CONTROL\fR for more details. +.PP +As with the agent configuration, the +.I snmptrapd.conf +directives can be divided into four distinct groups. +.SH TRAPD BEHAVIOUR +.IP "snmpTrapdAddr [<transport-specifier>:]<transport-address>[,...]" +defines a list of listening addresses, on which to receive +incoming SNMP notifications. +See the section +.B LISTENING ADDRESSES +in the +.I snmpd(8) +manual page for more information about the format of listening +addresses. +.IP +The default behaviour is to +listen on UDP port 162 on all IPv4 interfaces. +.IP "doNotRetainNotificationLogs yes" +disables support for the NOTIFICATION\-LOG\-MIB. +Normally the snmptrapd program keeps a record of the traps +received, which can be retrieved by querying +the \fCnlmLogTable\fR and \fCnlmLogvariableTable\fR tables. +This directive can be used to suppress this behaviour. +.IP +See the +.I snmptrapd(8) +manual page and the NOTIFICATION\-LOG\-MIB for details. +.IP "doNotLogTraps yes" +disables the logging of notifications altogether. +This is useful if the \fBsnmptrapd\fR application should +only run traphandle hooks and should not log traps to any location. +.IP "doNotFork yes" +do not fork from the calling shell. +.IP "pidFile PATH" +defines a file in which to store the process ID of the +notification receiver. By default, this ID is not saved. +.SH ACCESS CONTROL +Starting with release 5.3, it is necessary to explicitly specify +who is authorised to send traps and informs to the notification +receiver (and what types of processing these are allowed to trigger). +This uses an extension of the VACM model, used in the main SNMP agent. +.PP +There are currently three types of processing that can be specified: +.RS +.IP "log" +log the details of the notification - either in a specified file, +to standard output (or stderr), or via \fIsyslog\fR (or similar). +.IP "execute" +pass the details of the trap to a specified handler program, including +embedded perl. +.IP "net" +forward the trap to another notification receiver. +.RE +.PP +In the following directives, \fITYPES\fR will be a (comma-separated) +list of one or more of these tokens. Most commonly, this will +typically be \fIlog,execute,net\fR to cover any style of processing +for a particular category of notification. But it is perfectly +possible (even desirable) to limit certain notification sources to +selected processing only. +.IP "authCommunity TYPES COMMUNITY [SOURCE [OID | \-v VIEW ]]" +authorises traps (and SNMPv2c INFORM requests) with the specified +community to trigger the types of processing listed. +By default, this will allow any notification using this community +to be processed. The SOURCE field can be used to specify that the +configuration should only apply to notifications received from +particular sources - see \fIsnmpd.conf(5)\fR for more details. +.IP "authUser TYPES [\-s MODEL] USER [LEVEL [OID | \-v VIEW ]]" +authorises SNMPv3 notifications with the specified +user to trigger the types of processing listed. +By default, this will accept authenticated requests. +(\fIauthNoPriv\fR or \fIauthPriv\fR). The LEVEL field can +be used to allow unauthenticated notifications (\fInoauth\fR), +or to require encryption (\fIpriv\fR), just as for the SNMP agent. +.IP +With both of these directives, the OID (or \fI\-v VIEW\fR) field +can be used to retrict this configuration to the processing of +particular notifications. +.RS +.IP "Note:" +Unlike the VACM processing described in RFC 3415, this view is +\fBonly\fR matched against the \fCsnmpTrapOID\fR value of the +incoming notification. It is not applied to the payload varbinds +held within that notification. +.RE +.IP "authGroup TYPES [\-s MODEL] GROUP [LEVEL [OID | \-v VIEW ]]" +.IP "authAccess TYPES [\-s MODEL] GROUP VIEW [LEVEL [CONTEXT]]" +.IP "setAccess GROUP CONTEXT MODEL LEVEL PREFIX VIEW TYPES" +authorise notifications in the specified GROUP +(configured using the \fIgroup\fR directive) +to trigger the types of processing listed. +See \fIsnmpd.conf(5)\fR for more details. +.IP "createUser [-e ENGINEID] username (MD5|SHA) authpassphrase [DES|AES]" +See the +.I snmpd.conf(5) +manual page for a description of how to create SNMPv3 users. This +is roughly the same, but the file name changes to snmptrapd.conf from +snmpd.conf. +.IP "disableAuthorization yes" +will disable the above access control checks, and revert to the +previous behaviour of accepting all incoming notifications. +.IP +.\" XXX - Explain why this is a Bad Idea +.\" +.SH LOGGING +.IP "format1 FORMAT" +.IP "format2 FORMAT" +specify the format used to display SNMPv1 TRAPs and SNMPv2 +notifications respectively. Note that SNMPv2c and SNMPv3 +both use the same SNMPv2 PDU format. +.IP +See +.IR snmptrapd(8) +for the layout characters available. +.IP "ignoreAuthFailure yes" +instructs the receiver to ignore \fIauthenticationFailure\fR traps. +.RS +.IP Note: +This currently only affects the logging of such notifications. +\fIauthenticationFailure\fR traps will still be passed to trap +handler scripts, and forwarded to other notification receivers. +This behaviour should not be relied on, as it is likely +to change in future versions. +.RE +.IP "logOption string" +specifies where notifications should be logged - to standard +output, standard error, a specified file or via \fIsyslog\fR. +See the section LOGGING OPTIONS in the +\fIsnmpcmd(1)\fR manual page for details. +.IP "outputOption string" +specifies various characteristics of how OIDs and other values +should be displayed. +See the section OUTPUT OPTIONS in the +\fIsnmpcmd(1)\fR manual page for details. +.SH MySQL Logging +There are two configuration variables that work together to control +when queued traps are logged to the MySQL database. A non-zero +value must be specified for sqlSaveInterval to enable MySQL logging. +.RE +.IP "sqlMaxQueue max" +specifies the maximum number of traps to queue before a forced flush +to the MySQL database. +.RE +.IP "sqlSaveInterval seconds" +specified the number of seconds between periodic queue flushes. +A value of 0 for will disable MySQL logging. +.SH NOTIFICATION PROCESSING +As well as logging incoming notifications, they can also +be forwarded on to another notification receiver, or passed +to an external program for specialised processing. +.IP "traphandle OID|default PROGRAM [ARGS ...]" +invokes the specified program (with the given arguments) whenever a +notification is received that matches the OID token. For SNMPv2c and +SNMPv3 notifications, this token will be compared against the +\fCsnmpTrapOID\fR value taken from the notification. For SNMPv1 traps, +the generic and specific trap values and the enterprise OID will be +converted into the equivalent OID (following RFC 2576). +.IP +Typically, the OID token will be the name (or numeric OID) of a +NOTIFICATION-TYPE object, and the specified program will be invoked for +notifications that match this OID exactly. However this token also +supports a simple form of wildcard suffixing. By appending the character +\'*' to the OID token, the corresponding program will be invoked for any +notification based within subtree rooted at the specified OID. +For example, an OID token of \fC.1.3.6.1.4.1*\fP would match any enterprise +specific notification (including the specified OID itself). +An OID token of \fC.1.3.6.1.4.1.*\fP would would work in much the same way, +but would not match this exact OID - just notifications that lay strictly +below this root. +Note that this syntax does not support full regular expressions or +wildcards - an OID token of the form \fCoid.*.subids\fR is \fBnot\fC valid. +.IP +If the OID field is the token \fIdefault\fR then the program will be +invoked for any notification not matching another (OID specific) +\fItraphandle\fR entry. +.PP +Details of the notification are fed to the program via its standard input. +Note that this will always use the SNMPv2-style notification format, with +SNMPv1 traps being converted as per RFC 2576, before being passed to the +program. +The input format is as follows, one entry per line: +.RS +.IP HOSTNAME +The name of the host that sent the notification, as determined by +.IR gethostbyaddr(3) . +.br +.IP IPADDRESS +The IP address of the host that sent the notification. +.\" +.\" XXX - What about non-IPv4 transports? +.\" +.IP VARBINDS +A list of variable bindings describing the contents of the notification, +one per line. The first token on each line (up until a space) is the +OID of the varind, and the remainder of the line is its value. +The format of both of these are controlled by the \fIoutputOption\fR +directive (or similar configuration). +.IP +The first OID should always be \fCSNMPv2\-MIB::sysUpTime.0\fR, +and the second should be \fCSNMPv2\-MIB::snmpTrapOID.0\fR. +The remaining lines will contain the payload varbind list. +For SNMPv1 traps, the final OID will be \fCSNMPv2\-MIB::snmpTrapEnterprise.0\fR. +.br +.IP Example: +A \fBtraptoemail\fR script has been included in the Net-SNMP package that +can be used within a \fItraphandle\fR directive: +.br +.RS +.P +traphandle default /usr/bin/perl BINDIR/traptoemail \-s mysmtp.somewhere.com \-f admin@somewhere.com me@somewhere.com +.RE +.RE +.IP "forward OID|default DESTINATION" +forwards notifications that match the specified OID +to another receiver listening on DESTINATION. +The interpretation of OID (and \fIdefault\fR) is the same +as for the \fItraphandle\fR directive). +.IP +See the section +.B LISTENING ADDRESSES +in the +.I snmpd(8) +manual page for more information about the format of listening +addresses. +.RE +.SH NOTES +.IP o +The daemon blocks while executing the \fItraphandle\fR commands. +(This should +be fixed in the future with an appropriate signal catch and wait() +combination). +.IP o +All directives listed with a value of "yes" actually accept a range +of boolean values. These will accept any of \fI1\fR, \fIyes\fR or +\fItrue\fR to enable the corresponding behaviour, +or any of \fI0\fR, \fIno\fR or \fIfalse\fR to disable it. +The default in each case is for the feature to be turned off, so these +directives are typically only used to enable the appropriate behaviour. +.SH FILES +SYSCONFDIR/snmp/snmptrapd.conf +.SH "SEE ALSO" +snmp_config(5), snmptrapd(8), syslog(8), variables(5), snmpd.conf(5), netsnmp_config_api(3). + diff --git a/man/snmpusm.1.def b/man/snmpusm.1.def new file mode 100644 index 0000000..9061213 --- /dev/null +++ b/man/snmpusm.1.def @@ -0,0 +1,267 @@ +.TH SNMPUSM 1 "11 Dec 2009" VVERSIONINFO "Net-SNMP" +.SH NAME +snmpusm - creates and maintains SNMPv3 users on a network entity +.SH SYNOPSIS +.B snmpusm +[COMMON OPTIONS] [\-Cw] AGENT +.B create +USER [CLONEFROM-USER] +.br +.B snmpusm +[COMMON OPTIONS] AGENT +.B delete +USER +.br +.B snmpusm +[COMMON OPTIONS] AGENT +.B cloneFrom +USER CLONEFROM-USER +.br +.B snmpusm +[COMMON OPTIONS] [\-Ca] [\-Cx] AGENT +.B passwd +OLD-PASSPHRASE NEW-PASSPHRASE [USER] +.br +.B snmpusm +[COMMON OPTIONS] <\-Ca | \-Cx> \-Ck AGENT +.B passwd +OLD-KEY-OR-PASSPHRASE NEW-KEY-OR-PASSPHRASE [USER] +.br +.B snmpusm +[COMMON OPTIONS] [\-Ca] [\-Cx] AGENT +.B changekey +[USER] + +.SH DESCRIPTION +.B snmpusm +is an SNMP application that can be used to do simple maintenance on +the users known to an SNMP agent, by manipulating the agent's +User-based Security Module (USM) table. The user needs +write access to the usmUserTable MIB table. This tool can be +used to create, delete, clone, and change the passphrase of users +configured on a running SNMP agent. + +.SH OPTIONS +Common options for all +.B snmpusm +commands: +.TP +.BI \-CE " ENGINE-ID" +Set usmUserEngineID to be used as part of the index of the usmUserTable. +Default is to use the contextEngineID (set via \-E or probed) as the +usmUserEngineID. +.TP +.BI \-Cp " STRING" +Set the usmUserPublic value of the (new) user to the specified STRING. +.PP +Options for the +.B passwd +and +.B changekey +commands: +.TP +.BI \-Ca +Change the authentication key. +.TP +.BI \-Cx +Change the privacy key. +.TP +.BI \-Ck +Allows one to use localized key (must start with 0x) instead of passphrase. +When this option is used, either the \-Ca or \-Cx option (but not both) must also +be used. + +.SH CREATING USERS +.PP +An unauthenticated SNMPv3 user can be created using the command +.IP +.B snmpusm +[COMMON OPTIONS] AGENT create USER +.PP +This constructs an (inactive) entry in the usmUserTable, +with no authentication or privacy settings. +In principle, this user should be useable for 'noAuthNoPriv' requests, +but in practise the Net-SNMP agent will not allow such an entry +to be made active. The user can be created via the createAndWait +operation instead by using the \-Ca flag. This will prevent the user +from being marked as active in any agent until explicitly activated +later via the activate command. + +.PP +In order to activate this entry, it is necessary to "clone" an existing +user, using the command +.IP +.B snmpusm +[COMMON OPTIONS] AGENT cloneFrom USER CLONEFROM-USER +.PP +The USER entry then inherits the same authentication and privacy +settings (including pass phrases) as the CLONEFROM user. + +.PP +These two steps can be combined into one, by using the command +.IP +.B snmpusm +[COMMON OPTIONS] AGENT create USER CLONEFROM-USER + +.PP +The two forms of the +.B create +sub-command require that the user being created does not already exist. +The +.B cloneFrom +sub-command requires that the user being cloned to +.I does +already exist. + +.PP +Cloning is the only way to specify which authentication and privacy +protocols to use for a given user, and it is only possible to do this +once. Subsequent attempts to reclone onto the same user will appear +to succeed, but will be silently ignored. +This (somewhat unexpected) behaviour is mandated by the SNMPv3 +USM specifications (RFC 3414). +To change the authentication and privacy settings for a given user, +it is necessary to delete and recreate the user entry. +This is +.I not +necessary for simply changing the pass phrases (see below). +This means that the agent must be initialized with at least one +user for each combination of authentication and privacy protocols. +See the +.I snmpd.conf(5) +manual page for details of the +.B createUser +configuration directive. + +.SH DELETING USERS +A user can be deleted from the usmUserTable using the command +.IP +.B snmpusm +[COMMON OPTIONS] AGENT delete USER + +.SH CHANGING PASS PHRASES +User profiles contain private keys that are never +transmitted over the wire in clear text (regardless of whether the +administration requests are encrypted or not). +To change the secret key for a user, it is necessary to specify the +user's old passphrase as well as the new one. +This uses the command +.IP +.B snmpusm +[COMMON OPTIONS] [\-Ca] [\-Cx] AGENT passwd OLD-PASSPHRASE NEW-PASSPHRASE [USER] + +.PP +After cloning a new user entry from the appropriate template, +you should immediately change the new user's passphrase. + +.PP +If USER is not specified, this command will change the passphrase +of the (SNMPv3) user issuing the command. If the \-Ca or \-Cx options +are specified, then only the authentication or privacy keys are changed. If +these options are not specified, then both the authentication and privacy keys +are changed. + +.IP +.B snmpusm +[COMMON OPTIONS] [\-Ca] [\-Cx] AGENT changekey [USER] + +.PP +This command changes the key in a perfect-forward-secrecy compliant +way through a diffie-helman exchange. The remote agent must support +the SNMP\-USM\-DH\-OBJECTS\-MIB for this command to work. The resulting +keys are printed to the console and may be then set in future command +invocations using the \-\-defAuthLocalizedKey and \-\-defPrivLocalizedKey +options or in your snmp.conf file using the defAuthLocalizedKey and +defPrivLocalizedKey keywords. + +.PP +Note that since these keys are randomly generated based on a +diffie helman exchange, they are no longer derived from a more easily +typed password. They are, however, much more secure. + +.PP +To change from a localized key back to a password, the following variant +of the +.B passwd +sub-command is used: + +.IP +.B snmpusm +[COMMON OPTIONS] <\-Ca | \-Cx> \-Ck AGENT passwd OLD-KEY-OR-PASSPHRASE NEW-KEY-OR-PASSPHRASE [USER] + +.PP +Either the \-Ca or the \-Cx option must be specified. The OLD-KEY-OR-PASSPHRASE +and/or NEW-KEY-OR-PASSPHRASE arguments can either be a passphrase or a +localized key starting with "0x", e.g. as printed out by the +.B changekey +sub-command. + +.PP +Note that +.B snmpusm +REQUIRES an argument specifying the agent to query +as described in the .I snmpcmd(1) manual page. +.SH EXAMPLES +.PP +Let's assume for our examples that the following VACM and USM +configurations lines were in the snmpd.conf file for a Net-SNMP agent. +These lines set up a default user called "initial" with the +authentication passphrase "setup_passphrase" so that we can perform +the initial setup of an agent: +.PP +.RS +.nf +# VACM configuration entries +rwuser initial +# lets add the new user we'll create too: +rwuser wes +# USM configuration entries +createUser initial MD5 setup_passphrase DES +.fi +.RE +.PP +Note: the "initial" user's setup should be removed after creating a +real user that you grant administrative privileges to (like the user +"wes" we'll be creating in this example. +.PP +Note: passphrases must be 8 characters +.I minimum +in length. +.SS Create a new user +.PP +snmpusm \-v3 \-u initial \-n "" \-l authNoPriv \-a MD5 \-A setup_passphrase +localhost create wes initial +.IP +Creates a new user, here named "wes" using the user "initial" to do +it. "wes" is cloned from "initial" in the process, so he inherits +that user's passphrase ("setup_passphrase"). +.SS Change the user's passphrase +.PP +snmpusm \-v 3 \-u wes \-n "" \-l authNoPriv \-a MD5 \-A setup_passphrase +localhost passwd setup_passphrase new_passphrase +.IP +After creating the user "wes" with the same passphrase as the +"initial" user, we need to change his passphrase for him. The above +command changes it from "setup_passphrase", which was inherited from +the initial user, to "new_passphrase". +.SS Test the new user +.PP +snmpget \-v 3 \-u wes \-n "" \-l authNoPriv \-a MD5 \-A new_passphrase +localhost sysUpTime.0 +.IP +If the above commands were successful, this command should have +properly performed an authenticated SNMPv3 GET request to the agent. +.PP +Now, go remove the vacm "group" snmpd.conf entry for the "initial" +user and you have a valid user 'wes' that you can use for future +transactions instead of initial. + +.SH WARNING +Manipulating the usmUserTable using this command can +.I only +be done using SNMPv3. +This command will not work with the community-based versions, +even if they have write access to the table. + +.SH "SEE ALSO" +snmpd.conf(5), snmp.conf(5), RFC 3414 diff --git a/man/snmpvacm.1.def b/man/snmpvacm.1.def new file mode 100644 index 0000000..70b089e --- /dev/null +++ b/man/snmpvacm.1.def @@ -0,0 +1,373 @@ +.TH SNMPVACM 1 "05 Sep 2006" VVERSIONINFO "Net-SNMP" +.SH NAME +snmpvacm - creates and maintains SNMPv3 View-based Access Control entries on a network entity +.SH SYNOPSIS +.B snmpvacm +[COMMON OPTIONS] AGENT +.B createSec2Group +MODEL SECURITYNAME GROUPNAME +.br +.B snmpvacm +[COMMON OPTIONS] AGENT +.B deleteSec2Group +MODEL SECURITYNAME +.br +.B snmpvacm +[COMMON OPTIONS] AGENT +.B createView +[\-Ce] NAME SUBTREE MASK +.br +.B snmpvacm +[COMMON OPTIONS] AGENT +.B deleteView +NAME SUBTREE +.br +.B snmpvacm +[COMMON OPTIONS] AGENT +.B createAccess +GROUPNAME [CONTEXTPREFIX] MODEL LEVEL CONTEXTMATCH READVIEW WRITEVIEW NOTIFYVIEW +.br +.B snmpvacm +[COMMON OPTIONS] AGENT +.B deleteAccess +GROUPNAME [CONTEXTPREFIX] MODEL LEVEL +.br +.B snmpvacm +[COMMON OPTIONS] AGENT +.B createAuth +GROUPNAME [CONTEXTPREFIX] MODEL LEVEL AUTHTYPE CONTEXTMATCH VIEW +.br +.B snmpvacm +[COMMON OPTIONS] AGENT +.B deleteAuth +GROUPNAME [CONTEXTPREFIX] MODEL LEVEL AUTHTYPE + +.SH DESCRIPTION +.B snmpvacm +is an SNMP application that can be used to do simple maintenance on the +View-based Control Module (VACM) tables of an SNMP agent. +The SNMPv3 VACM specifications (see RFC2575) define assorted tables +to specify groups of users, MIB views, and authorised access settings. +These +.BR snmpvacm +commands effectively create or delete rows in the appropriate one of +these tables, and match the equivalent configure directives +which are documented in the +.I snmpd.conf(5) +man page. +.PP +A fuller explanation of how these operate can be found in the project FAQ. +.SH SUB-COMMANDS + +.SS createSec2Group \fRMODEL SECURITYNAME GROUPNAME\fP +.PP +Create an entry in the SNMPv3 security name to group table. This table +allows a single access control entry to be applied to a number of users +(or 'principals'), +and is indexed by the security model and security name values. +.PP +MODEL +.IP +An integer representing the security model, taking one of the following +values: +.br +1 - reserved for SNMPv1 +.br +2 - reserved for SNMPv2c +.br +3 - User-based Security Model (USM) + +.PP +SECURITYNAME +.IP +A string representing the security name for a principal (represented in +a security-model-independent format). For USM-based requests, the security +name is the same as the username. + +.PP +GROUPNAME +.IP +A string identifying the group that this entry (i.e. security name/model +pair) should belong to. This group name will then be referenced in the +access table (see +.B createAccess +below). +.PP +.SS deleteSec2Group \fRMODEL SECURITYNAME\fP +.PP +Delete an entry from the SNMPv3 security name to group table, thus removing +access control settings for the given principal. The entry to be removed is +indexed by the MODEL and SECURITYNAME values, which should match those used +in the corresponding +.B createSec2Group +command (or equivalent). + +.SS createView \fR[\-Ce] NAME SUBTREE MASK\fP +.PP +Create an entry in the SNMPv3 MIB view table. +A MIB view consists of a family of view subtrees which may be individually +included in or (occasionally) excluded from the view. Each view subtree is +defined by a combination of an OID subtree together with a bit string mask. +The view table is indexed by the view name and subtree OID values. +.PP +[\-Ce] +.IP +An optional flag to indicate that this view subtree should be excluded +from the named view. +If not specified, the default is to include the subtree in the view. +When constructing a view from a mixture of included and excluded subtrees, +the excluded subtrees should be defined first - particularly if the named +view is already referenced in one or more access entries. +.PP +NAME +.IP +A string identifying a particular MIB view, of which this OID subtree/mask +forms part (possibly the only part). +.PP +SUBTREE +.IP +The OID defining the root of the subtree to add to (or exclude from) the +named view. +.PP +MASK +.IP +A bit mask indicating which sub-identifiers of the associated subtree OID +should be regarded as significant. + +.SS deleteView \fRNAME SUBTREE\fP +Delete an entry from the SNMPv3 view table, thus removing the subtree from +the given MIB view. +Removing the final (or only) subtree will result in the deletion of the view. +The entry to be removed is indexed by the NAME and SUBTREE values, which +should match those used in the corresponding +.B createView +command (or equivalent). +.PP +When removing subtrees from a mixed view (i.e. containing both included and +excluded subtrees), the included subtrees should be removed first. + +.SS createAccess \fRGROUPNAME [CONTEXTPREFIX] MODEL LEVEL CONTEXTMATCH READVIEW WRITEVIEW NOTIFYVIEW\fP +Create an entry in the SNMPv3 access table, thus allowing a certain level +of access to particular MIB views for the principals in the specified group +(given suitable security model and levels in the request). +The access table is indexed by the group name, context prefix, security model +and security level values. +.PP +GROUPNAME +.IP +The name of the group that this access entry applies to +(as set up by a +.B createSec2Group +command, or equivalent) +.PP +CONTEXTPREFIX +.IP +A string representing a context name (or collection of context names) +which this access entry applies to. +The interpretation of this string depends on the value of the +CONTEXTMATCH field (see below). +.IP +If omitted, this will default to the null context "". +.PP +MODEL +.IP +An integer representing the security model, taking one of the following +values: +.br +1 - reserved for SNMPv1 +.br +2 - reserved for SNMPv2c +.br +3 - User-based Security Model (USM) +.PP +LEVEL +.IP +An integer representing the minimal security level, taking one of the following +values: +.br +1 - noAuthNoPriv +.br +2 - authNoPriv +.br +3 - authPriv +.IP +This access entry will be applied to requests of this level or higher +(where authPriv is higher than authNoPriv which is in turn higher than +noAuthNoPriv). +.PP +CONTEXTMATCH +.IP +Indicates how to interpret the CONTEXTPREFIX value. +If this field has the value '1' (representing 'exact') then the context +name of a request must match the CONTEXTPREFIX value exactly for this +access entry to be applicable to that request. +.IP +If this field has the value '2' (representing 'prefix') then the initial +substring of the context name of a request must match the CONTEXTPREFIX +value for this access entry to be applicable to that request. +This provides a simple form of wildcarding. +.PP +READVIEW +.IP +The name of the MIB view +(as set up by +.B createView +or equivalent) +defining the MIB objects for which this request may request the current values. +.IP +If there is no view with this name, then read access is not granted. +.PP +WRITEVIEW +.IP +The name of the MIB view +(as set up by +.B createView +or equivalent) +defining the MIB objects for which this request may potentially SET new values. +.IP +If there is no view with this name, then read access is not granted. +.PP +NOTIFYVIEW +.IP +The name of the MIB view +(as set up by +.B createView +or equivalent) +defining the MIB objects which may be included in notification request. +.IP +Note that this aspect of access control is not currently supported. + +.SS deleteAccess \fRGROUPNAME [CONTEXTPREFIX] MODEL LEVEL\fP +Delete an entry from the SNMPv3 access table, thus removing the specified +access control settings. +The entry to be removed is indexed by the group name, context prefix, +security model and security level values, +which should match those used in the corresponding +.B createAccess +command (or equivalent). + +.SS createAuth \fRGROUPNAME [CONTEXTPREFIX] MODEL LEVEL AUTHTYPE CONTEXTMATCH VIEW\fP +Create an entry in the Net-SNMP extension to the standard access table, +thus allowing a certain type of access to the MIB view for the principals +in the specified group. +The interpretation of GROUPNAME, CONTEXTPREFIX, MODEL, LEVEL and CONTEXTMATCH +are the same as for the +.B createAccess +directive. +The extension access table is indexed by the group name, context prefix, +security model, security level and authtype values. +.PP +AUTHTYPE +.IP +The style of access that this entry should be applied to. +See +.I "snmpd.conf(5)" +and +.I "snmptrapd.conf(5)" +for details of valid tokens. +.PP +VIEW +.IP +The name of the MIB view +(as set up by +.B createView +or equivalent) +defining the MIB objects for which this style of access is authorized. + +.SS deleteAuth \fRGROUPNAME [CONTEXTPREFIX] MODEL LEVEL AUTHTYPE\fP +Delete an entry from the extension access table, thus removing the specified +access control settings. +The entry to be removed is indexed by the group name, context prefix, +security model, security level and authtype values, +which should match those used in the corresponding +.B createAuth +command (or equivalent). + +.PP +Note that +.B snmpget +REQUIRES an argument specifying the agent to query +as described in the .I snmpcmd(1) manual page. + +.SH EXAMPLES +.PP +Given a pre-existing user +.I dave +(which could be set up using the +.I snmpusm(1) +command), +we could configure full read-write access to the whole OID tree +using the commands: + +.IP +snmpvacm localhost createSec2Group 3 dave RWGroup +.IP +snmpvacm localhost createView all .1 80 +.IP +snmpvacm localhost createAccess RWGroup 3 1 1 all all none +.PP +This creates a new security group named "RWGroup" containing the SNMPv3 user "dave", +a new view "all" containing the full OID tree based on +.I .iso(1) +, and then allows those users in the group "RWGroup" (i.e. "dave") +both read- and write-access to the view "all" (i.e. the full OID tree) +when using authenticated SNMPv3 requests. + +.PP +As a second example, +we could set up read-only access to a portion +of the OID tree using the commands: + +.IP +snmpvacm localhost createSec2Group 3 wes ROGroup +.IP +snmpvacm localhost createView sysView system fe +.IP +snmpvacm localhost createAccess ROGroup 3 0 1 sysView none none +.PP +This creates a new security group named "ROGroup" containing the (pre-existing) +user "wes", a new view "sysView" containing just the OID tree based on +.I .iso(1).org(3).dod(6).inet(1).mgmt(2).mib\-2(1).system(1) +, and then allows those users in the group "ROGroup" (i.e. "wes") +read-access, but not write-access to the view "sysView" (i.e. the system group). + +.SH "EXIT STATUS" + +.PP +The following exit values are returned: +.PP +0 - Successful completion +.PP +1 - A usage syntax error (which displays a suitable usage message) +or a request timeout. +.PP +2 - An error occurred while executing the command +(which also displays a suitable error message). + +.SH "LIMITATIONS" + +This utility does not support the configuration of new community strings, +so is only of use for setting up new access control for SNMPv3 requests. +It can be used to amend the access settings for existing community strings, +but not to set up new ones. + +.PP +The use of numeric +parameters for +.B secLevel +and +.B contextMatch +parameters is less than intuitive. +These commands do not provide the full flexibility of the +equivalent config file directives. + +.PP +There is (currently) no equivalent to the one-shot +configure directives +.I rouser +and +.I rwuser. + +.SH "SEE ALSO" +snmpcmd(1), snmpusm(1), +snmpd.conf(5), snmp.conf(5), RFC 2575, Net-SNMP project FAQ diff --git a/man/snmpwalk.1.def b/man/snmpwalk.1.def new file mode 100644 index 0000000..ef78660 --- /dev/null +++ b/man/snmpwalk.1.def @@ -0,0 +1,142 @@ +.\" -*- nroff -*- +.\" Portions of this file are subject to the following copyright. See +.\" the Net-SNMP COPYING file for more details and other copyrights +.\" that may apply: +.\" /*********************************************************** +.\" Copyright 1988, 1989 by Carnegie Mellon University +.\" +.\" All Rights Reserved +.\" +.\" Permission to use, copy, modify, and distribute this software and its +.\" documentation for any purpose and without fee is hereby granted, +.\" provided that the above copyright notice appear in all copies and that +.\" both that copyright notice and this permission notice appear in +.\" supporting documentation, and that the name of CMU not be +.\" used in advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" +.\" CMU DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING +.\" ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL +.\" CMU BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR +.\" ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, +.\" WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, +.\" ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS +.\" SOFTWARE. +.\" ******************************************************************/ +.TH SNMPWALK 1 "28 May 2007" VVERSIONINFO "Net-SNMP" +.SH NAME +snmpwalk - retrieve a subtree of management values using SNMP GETNEXT requests +.SH SYNOPSIS +.B snmpwalk +[APPLICATION OPTIONS] [COMMON OPTIONS] AGENT [OID] +.SH DESCRIPTION +.B snmpwalk +is an SNMP application that uses SNMP GETNEXT requests to query a +network entity for a tree of information. +.PP +An object identifier (OID) may be given on the command line. This OID +specifies which portion of the object identifier space will be +searched using GETNEXT requests. All variables in the subtree +below the given OID are queried and their values presented to the user. +Each variable name is given in the format specified in +.IR variables(5) . +.PP +If no OID argument is present, +.B snmpwalk +will search the subtree rooted at SNMPv2\-SMI::mib\-2 +(including any MIB object values from other MIB modules, +that are defined as lying within this subtree). +If the network entity has an error processing the request packet, an +error packet will be returned and a message will be shown, helping to +pinpoint why the request was malformed. +.PP +If the tree search causes attempts to search beyond the end of the +MIB, the message "End of MIB" will be displayed. +.SH OPTIONS +.TP 8 +.B \-Cc +Do not check whether the returned OIDs are increasing. Some agents +(LaserJets are an example) return OIDs out of order, but can +complete the walk anyway. Other agents return OIDs that are out of +order and can cause +.B snmpwalk +to loop indefinitely. By default, +.B snmpwalk +tries to detect this behavior and warns you when it hits an agent +acting illegally. Use +.B \-Cc +to turn off this check. +.TP +.B \-CE {OID} +End the walk at the specified OID, rather than a simple subtree. +This can be used to walk a partial subtree, selected columns of +a table, or even two or more tables within a single command. +.TP +.B \-Ci +Include the given OID in the search range. Normally +.B snmpwalk +uses GETNEXT requests starting with the OID you specified and returns +all results in the MIB subtree rooted at that OID. Sometimes, you may +wish to include the OID specified on the command line in the printed +results if it is a valid OID in the tree itself. This option lets you +do this explicitly. +.TP +.B \-CI +In fact, the given OID will be retrieved automatically if the main +subtree walk returns no useable values. This allows a walk of a +single instance to behave as generally expected, and return the +specified instance value. +This option turns off this final GET request, so a walk of a +single instance will return nothing. +.TP +.B \-Cp +Upon completion of the walk, print the number of variables found. +.TP +.B \-Ct +Upon completion of the walk, print the total wall-clock time it took +to collect the data (in seconds). Note that the timer is started just +before the beginning of the data request series and stopped just after +it finishes. Most importantly, this means that it does not include +snmp library initialization, shutdown, argument processing, and any +other overhead. +.PP +In addition to these options, +.B snmpwalk +takes the common options described in the +.I snmpcmd(1) +manual page. +.SH EXAMPLES +.br +Note that +.B snmpbulkget +REQUIRES an argument specifying the agent to query +and at most one OID argument, as described there. +The command: +.PP +snmpwalk \-Os \-c public \-v 1 zeus system +.PP +will retrieve all of the variables under system: +.PP +sysDescr.0 = STRING: "SunOS zeus.net.cmu.edu 4.1.3_U1 1 sun4m" +.br +sysObjectID.0 = OID: enterprises.hp.nm.hpsystem.10.1.1 +.br +sysUpTime.0 = Timeticks: (155274552) 17 days, 23:19:05 +.br +sysContact.0 = STRING: "" +.br +sysName.0 = STRING: "zeus.net.cmu.edu" +.br +sysLocation.0 = STRING: "" +.br +sysServices.0 = INTEGER: 72 +.br +(plus the contents of the sysORTable). + +The command: +.PP +snmpwalk \-Os \-c public \-v 1 \-CE sysORTable zeus system +.PP +will retrieve the scalar values, but omit the sysORTable. +.SH "SEE ALSO" +snmpcmd(1), snmpbulkwalk(1), variables(5). diff --git a/man/tkmib.1.def b/man/tkmib.1.def new file mode 100644 index 0000000..f0253b9 --- /dev/null +++ b/man/tkmib.1.def @@ -0,0 +1,15 @@ +.TH tkmib "1" "16 Nov 2006" VVERSIONINFO "Net-SNMP" +.SH NAME +tkmib - an interactive graphical MIB browser for SNMP +.SH SYNOPSIS +.PP +.B tkmib +.SH DESCRIPTION +.PP +Simple Network Management Protocol (SNMP) provides a framework for +exchange of the management information between the agents (servers) +and clients. The Management Information Bases (MIBs) contain a formal +description of a set of network objects that can be managed using the +SNMP for a particular agent. \fBtkmib\fR is a graphical user interface +for browsing the MIBs. It is also capable of sending or retrieving the +SNMP management information to/from the remote agents interactively. diff --git a/man/traptoemail.1.def b/man/traptoemail.1.def new file mode 100644 index 0000000..4080f36 --- /dev/null +++ b/man/traptoemail.1.def @@ -0,0 +1,22 @@ +.TH traptoemail "1" "16 Nov 2006" VVERSIONINFO "Net-SNMP" +.SH NAME +traptoemail - snmptrapd handler script to convert snmp traps into emails +.SH SYNOPSIS +.PP +.B traptoemail +[\fI\-f FROM\fR] +[\fI\-s SMTPSERVER\fR] +ADDRESSES +.SH DESCRIPTION +.PP +converts snmp traps into email messages. +.SH OPTIONS +.TP +.B \-f FROM +sender address, defaults to "root" +.TP +.B \-s SMTPSERVER +SMTP server, defaults to "localhost" +.TP +.B ADDRESSES +recipient addresses diff --git a/man/variables.5.def b/man/variables.5.def new file mode 100644 index 0000000..14ee5e2 --- /dev/null +++ b/man/variables.5.def @@ -0,0 +1,178 @@ +.\" -*- nroff -*- +.\" Portions of this file are subject to the following copyright. See +.\" the Net-SNMP COPYING file for more details and other copyrights +.\" that may apply: +.\" /*********************************************************** +.\" Copyright 1988, 1989 by Carnegie Mellon University +.\" +.\" All Rights Reserved +.\" +.\" Permission to use, copy, modify, and distribute this software and its +.\" documentation for any purpose and without fee is hereby granted, +.\" provided that the above copyright notice appear in all copies and that +.\" both that copyright notice and this permission notice appear in +.\" supporting documentation, and that the name of CMU not be +.\" used in advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" +.\" CMU DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING +.\" ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL +.\" CMU BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR +.\" ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, +.\" WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, +.\" ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS +.\" SOFTWARE. +.\" ******************************************************************/ +.TH VARIABLES 5 "01 Oct 2010" VVERSIONINFO "Net-SNMP" +.SH NAME + variables - Format of specifying variable names to SNMP tools. +.SH DESCRIPTION +The syntax and semantics of management information in SNMP is +given by the definitions of MIB objects, loaded from one or more +MIB files (or "MIB modules"). These definitions are not strictly +required for the SNMP protocol to operate correctly, but are typically +needed by SNMP client applications to display information in a +meaningful manner. + +The MIB file also serves as a design document when developing an SNMP +agent (or sub-agent) that provides this information, and ensures that +client and server share a common understanding about what management +information represents. + +.SH OIDs +MIB objects are specified using Object Identifiers (OIDs), which can +take a number of forms. Note that all of the examples in this section +refer to the same MIB object. +.SS Numeric OIDs +The fundamental format of an OID is a sequence of integer values +(or "subidentifiers"), typically written using dots to separate +the individual subidentifiers. +.RS + .1.3.6.1.2.1.1.1 +.RE +This is the format that is used within the SNMP protocol itself, +in the packets that are sent over the network. +.PP +This form of representing an OID does not require MIB files or MIB +object definitions to be available. However it does rely on the +client application and/or network administrator knowing what a +given numeric OID refers to. As such, it is not a particularly +helpful representation to anyone just starting out with SNMP. +.PP +This format can be obtained by giving the command-line option +-On +to most Net-SNMP commands. + +.SS Full OID path +A similar (but somewhat more informative) format uses the same +dotted list representation, but with the numeric subidentifiers +replaced by names, taken from the relevant MIB file(s). +.RS + .iso.org.dod.internet.mgmt.mib-2.system.sysDescr +.RE +This uniquely identifies a particular MIB object (as with the numeric +OID), but the list of names should hopefully give some indication as +to what information this object represents. However it does rely on +the relevant MIB files being available (as do all formats other than +the purely numeric OID). Such OIDs also tend to be fairly long! +.PP +This format can be obtained by giving the command-line option +-Of +to most Net-SNMP commands. +.PP +A variant of this (typically used when writing OIDs in descriptive +text, rather than running programs), is to combine the name and +numeric subidentifier: +.RS + .iso(1).org(3).dod(6).internet(1).mgmt(2).mib-2(1).system(1).sysDescr(1) +.RE + +.SS Module-qualified OIDs +An alternative way to (more-or-less) uniquely specify an OID, +is to give the name of the MIB object, together with the MIB +module where it is defined. +.RS +SNMPv2-MIB::sysDescr +.RE +MIB object names are unique within a given module, so as long +as there are not two MIB modules with the same name (which is +unusual, though not unheard of), this format specifies the +desired object in a reasonably compact form. It also makes +it relatively easy to find the definition of the MIB object. +.PP +This is the default format for displaying OIDs in Net-SNMP applications. +It can also be specified explicitly by giving the command-line option +-OS +to most Net-SNMP commands. + +.SS Object name +Possibly the most common form for specifying MIB objects is +using the name of the object alone - without the full path or +the name of the module that defines it. +.RS +sysDescr +.RE +This is by far the shortest and most convenient way to refer to +a MIB object. However the danger is that if two MIB modules each +define a MIB object with the same name (which is perfectly legal +in some circumstances), then it's not necessarily clear which MIB +object is actually meant. +For day-to-day use, particularly when using standard MIB objects, +this is \fIprobaby\fP safe. +But it's important to be aware of the potential ambiguities. +.PP +This format can be obtained by giving the command-line option +-Os +to most Net-SNMP commands. + +.SS UCD-format +Previous versions of the code (UCD v4.x and earlier) used a +simple approach to shortening the way OIDs were specified. +If the full path of the OID began with +\fC.iso.org.dod.internet.mgmt.mib-2\fP +then this prefix was removed from the OID before displaying it. +All other OIDs were displayed in full. +.PP +Similarly, if an OID was passed to the UCD library that did +not begin with a dot (and wasn't in the module::name format), +then the same prefix was prepended. The example OID from the +formats listed above would therefore be given or displayed as +.RS +system.sysDescr +.RE +The inconsistent handling of OIDs, depending on their location +within the OID tree, proved to be more trouble than it was worth, +and this format is no longer recommended. +.PP +The previous behaviour can be obtained by giving the command-line +option +-Ou +(for displaying output), or +-Iu +(for interpreting input OIDs without a leading dot) +to most Net-SNMP commands. +.\" +.\" ==================================== +.\" +.\" ToDo: +.\" Instances: +.\" Scalars +.\" Tables & indexing +.\" string indexes - 'abc' vs "abc" +'\" Internal objects +.\" +.\" ? Syntax types +.\" +.\" ==================================== +.\".PP +.\"The description of the variables in the MIB is given in the set of MIB +.\"files defined by the MIBS environment variable (or the default list +.\"defined at compilation time) and the MIB files in the +.\"DATADIR/snmp/mibs directory (or the MIBDIRS environment variable). +.SH "SEE ALSO" +snmpcmd(1) +.SH BUGS +The parser of the MIB files file is not expected to handle bizarre +(although correct) interpretations of the ASN.1 notation. + + |