diff options
Diffstat (limited to 'torrus/doc')
51 files changed, 12388 insertions, 0 deletions
diff --git a/torrus/doc/Makefile.am b/torrus/doc/Makefile.am new file mode 100644 index 000000000..336762e20 --- /dev/null +++ b/torrus/doc/Makefile.am @@ -0,0 +1,105 @@ + +# Copyright (C) 2002 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: Makefile.am,v 1.1 2010-12-27 00:04:32 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# + +SUBDIRS = . manpages + +SUBST = @abs_top_builddir@/setup_tools/substvars.sh + +CLEANFILES = $(POD_FILES) $(nodist_pkgdoc_DATA) +EXTRA_DIST = $(SRCPOD) + +SRCPOD = \ + install.pod.in \ + nodeid_usage.pod.in \ + reporting_setup.pod.in \ + rpnexpr.pod.in \ + rrfw_torrus_migration.pod.in \ + scalability.pod.in \ + snmpdiscovery.pod.in \ + stylingprofile.pod.in \ + userguide.pod.in \ + vendorsupport.pod.in \ + webintf.pod.in \ + xmlconfig.pod.in + +POD_FILES = \ + install.pod \ + nodeid_usage.pod \ + reporting_setup.pod \ + rpnexpr.pod \ + rrfw_torrus_migration.pod \ + scalability.pod \ + snmpdiscovery.pod \ + stylingprofile.pod \ + userguide.pod \ + vendorsupport.pod \ + webintf.pod \ + xmlconfig.pod + + +pkgdocdir = @pkgdocdir@ + +if POD2TEXT_PRESENT +nodist_pkgdoc_DATA = \ + install.txt \ + nodeid_usage.txt \ + reporting_setup.txt \ + rpnexpr.txt \ + rrfw_torrus_migration.txt \ + scalability.txt \ + snmpdiscovery.txt \ + stylingprofile.txt \ + userguide.txt \ + vendorsupport.txt \ + webintf.txt \ + xmlconfig.txt +endif + +devdocdir = $(pkgdocdir)/devdoc + +dist_devdoc_DATA = \ + devdoc/architecture.pod \ + devdoc/devdiscover.pod \ + devdoc/progstyle.pod \ + devdoc/reqs.0.0.pod \ + devdoc/reqs.0.1.pod \ + devdoc/torrus_roadmap.pod \ + devdoc/wd.distributed.pod \ + devdoc/wd.messaging.pod \ + devdoc/wd.monitor-escalation.pod \ + devdoc/wd.uptime-mon.pod + +SUFFIXES = .pod.in .pod .txt + +.PRECIOUS: $(POD_FILES) + +.pod.in.pod: + $(SUBST) $< > $@ + +if POD2TEXT_PRESENT +.pod.txt: + $(POD2TEXT) $< > $@ +endif + +htdocs: $(POD_FILES) + cd manpages; make pods + HTMLDIR=@abs_top_builddir@/../htdocs $(SHELL) mkhtdocs.sh + diff --git a/torrus/doc/Makefile.in b/torrus/doc/Makefile.in new file mode 100644 index 000000000..6c768bbfd --- /dev/null +++ b/torrus/doc/Makefile.in @@ -0,0 +1,620 @@ +# Makefile.in generated by automake 1.9.6 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, +# 2003, 2004, 2005 Free Software Foundation, Inc. +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ + +# Copyright (C) 2002 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: Makefile.in,v 1.1 2010-12-27 00:04:31 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# + +srcdir = @srcdir@ +top_srcdir = @top_srcdir@ +VPATH = @srcdir@ +pkgdatadir = $(datadir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +top_builddir = .. +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +INSTALL = @INSTALL@ +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +build_triplet = @build@ +host_triplet = @host@ +subdir = doc +DIST_COMMON = $(dist_devdoc_DATA) $(srcdir)/Makefile.am \ + $(srcdir)/Makefile.in +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/configure.ac +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +mkinstalldirs = $(install_sh) -d +CONFIG_CLEAN_FILES = +SOURCES = +DIST_SOURCES = +RECURSIVE_TARGETS = all-recursive check-recursive dvi-recursive \ + html-recursive info-recursive install-data-recursive \ + install-exec-recursive install-info-recursive \ + install-recursive installcheck-recursive installdirs-recursive \ + pdf-recursive ps-recursive uninstall-info-recursive \ + uninstall-recursive +am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; +am__vpath_adj = case $$p in \ + $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \ + *) f=$$p;; \ + esac; +am__strip_dir = `echo $$p | sed -e 's|^.*/||'`; +am__installdirs = "$(DESTDIR)$(devdocdir)" "$(DESTDIR)$(pkgdocdir)" +dist_devdocDATA_INSTALL = $(INSTALL_DATA) +nodist_pkgdocDATA_INSTALL = $(INSTALL_DATA) +DATA = $(dist_devdoc_DATA) $(nodist_pkgdoc_DATA) +ETAGS = etags +CTAGS = ctags +DIST_SUBDIRS = $(SUBDIRS) +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +ACLOCAL = @ACLOCAL@ +AMTAR = @AMTAR@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +CYGPATH_W = @CYGPATH_W@ +DEFS = @DEFS@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +FIND = @FIND@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +KILL = @KILL@ +LIBOBJS = @LIBOBJS@ +LIBS = @LIBS@ +LTLIBOBJS = @LTLIBOBJS@ +MAKEINFO = @MAKEINFO@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +PERL = @PERL@ +PERLINC = @PERLINC@ +POD2MAN = @POD2MAN@ +POD2MAN_PRESENT_FALSE = @POD2MAN_PRESENT_FALSE@ +POD2MAN_PRESENT_TRUE = @POD2MAN_PRESENT_TRUE@ +POD2TEXT = @POD2TEXT@ +POD2TEXT_PRESENT_FALSE = @POD2TEXT_PRESENT_FALSE@ +POD2TEXT_PRESENT_TRUE = @POD2TEXT_PRESENT_TRUE@ +RM = @RM@ +SED = @SED@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +SLEEP = @SLEEP@ +STRIP = @STRIP@ +SU = @SU@ +VERSION = @VERSION@ +ac_ct_STRIP = @ac_ct_STRIP@ +am__leading_dot = @am__leading_dot@ +am__tar = @am__tar@ +am__untar = @am__untar@ +bindir = @bindir@ +build = @build@ +build_alias = @build_alias@ +build_cpu = @build_cpu@ +build_os = @build_os@ +build_vendor = @build_vendor@ +cachedir = @cachedir@ +cfgdefdir = @cfgdefdir@ +datadir = @datadir@ +dbhome = @dbhome@ +defrrddir = @defrrddir@ +distxmldir = @distxmldir@ +enable_pkgonly = @enable_pkgonly@ +enable_varperm = @enable_varperm@ +exec_prefix = @exec_prefix@ +exmpdir = @exmpdir@ +host = @host@ +host_alias = @host_alias@ +host_cpu = @host_cpu@ +host_os = @host_os@ +host_vendor = @host_vendor@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localstatedir = @localstatedir@ +logdir = @logdir@ +mandir = @mandir@ +mansec_misc = @mansec_misc@ +mansec_usercmd = @mansec_usercmd@ +mkdir_p = @mkdir_p@ +oldincludedir = @oldincludedir@ +perlithreads = @perlithreads@ +perllibdir = @perllibdir@ +perllibdirs = @perllibdirs@ +piddir = @piddir@ +pkgbindir = @pkgbindir@ +pkgdocdir = @pkgdocdir@ +pkghome = @pkghome@ +plugdevdisccfgdir = @plugdevdisccfgdir@ +pluginsdir = @pluginsdir@ +plugtorruscfgdir = @plugtorruscfgdir@ +plugwrapperdir = @plugwrapperdir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +reportsdir = @reportsdir@ +sbindir = @sbindir@ +scriptsdir = @scriptsdir@ +seslockdir = @seslockdir@ +sesstordir = @sesstordir@ +sharedstatedir = @sharedstatedir@ +siteconfdir = @siteconfdir@ +sitedir = @sitedir@ +sitexmldir = @sitexmldir@ +supdir = @supdir@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ +tmpldir = @tmpldir@ +tmpluserdir = @tmpluserdir@ +torrus_user = @torrus_user@ +var_group = @var_group@ +var_mode = @var_mode@ +var_user = @var_user@ +varprefix = @varprefix@ +webplaindir = @webplaindir@ +webscriptsdir = @webscriptsdir@ +wrapperdir = @wrapperdir@ +SUBDIRS = . manpages +SUBST = @abs_top_builddir@/setup_tools/substvars.sh +CLEANFILES = $(POD_FILES) $(nodist_pkgdoc_DATA) +EXTRA_DIST = $(SRCPOD) +SRCPOD = \ + install.pod.in \ + nodeid_usage.pod.in \ + reporting_setup.pod.in \ + rpnexpr.pod.in \ + rrfw_torrus_migration.pod.in \ + scalability.pod.in \ + snmpdiscovery.pod.in \ + stylingprofile.pod.in \ + userguide.pod.in \ + vendorsupport.pod.in \ + webintf.pod.in \ + xmlconfig.pod.in + +POD_FILES = \ + install.pod \ + nodeid_usage.pod \ + reporting_setup.pod \ + rpnexpr.pod \ + rrfw_torrus_migration.pod \ + scalability.pod \ + snmpdiscovery.pod \ + stylingprofile.pod \ + userguide.pod \ + vendorsupport.pod \ + webintf.pod \ + xmlconfig.pod + +@POD2TEXT_PRESENT_TRUE@nodist_pkgdoc_DATA = \ +@POD2TEXT_PRESENT_TRUE@ install.txt \ +@POD2TEXT_PRESENT_TRUE@ nodeid_usage.txt \ +@POD2TEXT_PRESENT_TRUE@ reporting_setup.txt \ +@POD2TEXT_PRESENT_TRUE@ rpnexpr.txt \ +@POD2TEXT_PRESENT_TRUE@ rrfw_torrus_migration.txt \ +@POD2TEXT_PRESENT_TRUE@ scalability.txt \ +@POD2TEXT_PRESENT_TRUE@ snmpdiscovery.txt \ +@POD2TEXT_PRESENT_TRUE@ stylingprofile.txt \ +@POD2TEXT_PRESENT_TRUE@ userguide.txt \ +@POD2TEXT_PRESENT_TRUE@ vendorsupport.txt \ +@POD2TEXT_PRESENT_TRUE@ webintf.txt \ +@POD2TEXT_PRESENT_TRUE@ xmlconfig.txt + +devdocdir = $(pkgdocdir)/devdoc +dist_devdoc_DATA = \ + devdoc/architecture.pod \ + devdoc/devdiscover.pod \ + devdoc/progstyle.pod \ + devdoc/reqs.0.0.pod \ + devdoc/reqs.0.1.pod \ + devdoc/torrus_roadmap.pod \ + devdoc/wd.distributed.pod \ + devdoc/wd.messaging.pod \ + devdoc/wd.monitor-escalation.pod \ + devdoc/wd.uptime-mon.pod + +SUFFIXES = .pod.in .pod .txt +all: all-recursive + +.SUFFIXES: +.SUFFIXES: .pod.in .pod .txt +$(srcdir)/Makefile.in: $(srcdir)/Makefile.am $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh \ + && exit 0; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu doc/Makefile'; \ + cd $(top_srcdir) && \ + $(AUTOMAKE) --gnu doc/Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ + esac; + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +uninstall-info-am: +install-dist_devdocDATA: $(dist_devdoc_DATA) + @$(NORMAL_INSTALL) + test -z "$(devdocdir)" || $(mkdir_p) "$(DESTDIR)$(devdocdir)" + @list='$(dist_devdoc_DATA)'; for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + f=$(am__strip_dir) \ + echo " $(dist_devdocDATA_INSTALL) '$$d$$p' '$(DESTDIR)$(devdocdir)/$$f'"; \ + $(dist_devdocDATA_INSTALL) "$$d$$p" "$(DESTDIR)$(devdocdir)/$$f"; \ + done + +uninstall-dist_devdocDATA: + @$(NORMAL_UNINSTALL) + @list='$(dist_devdoc_DATA)'; for p in $$list; do \ + f=$(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(devdocdir)/$$f'"; \ + rm -f "$(DESTDIR)$(devdocdir)/$$f"; \ + done +install-nodist_pkgdocDATA: $(nodist_pkgdoc_DATA) + @$(NORMAL_INSTALL) + test -z "$(pkgdocdir)" || $(mkdir_p) "$(DESTDIR)$(pkgdocdir)" + @list='$(nodist_pkgdoc_DATA)'; for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + f=$(am__strip_dir) \ + echo " $(nodist_pkgdocDATA_INSTALL) '$$d$$p' '$(DESTDIR)$(pkgdocdir)/$$f'"; \ + $(nodist_pkgdocDATA_INSTALL) "$$d$$p" "$(DESTDIR)$(pkgdocdir)/$$f"; \ + done + +uninstall-nodist_pkgdocDATA: + @$(NORMAL_UNINSTALL) + @list='$(nodist_pkgdoc_DATA)'; for p in $$list; do \ + f=$(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(pkgdocdir)/$$f'"; \ + rm -f "$(DESTDIR)$(pkgdocdir)/$$f"; \ + done + +# This directory's subdirectories are mostly independent; you can cd +# into them and run `make' without going through this Makefile. +# To change the values of `make' variables: instead of editing Makefiles, +# (1) if the variable is set in `config.status', edit `config.status' +# (which will cause the Makefiles to be regenerated when you run `make'); +# (2) otherwise, pass the desired values on the `make' command line. +$(RECURSIVE_TARGETS): + @failcom='exit 1'; \ + for f in x $$MAKEFLAGS; do \ + case $$f in \ + *=* | --[!k]*);; \ + *k*) failcom='fail=yes';; \ + esac; \ + done; \ + dot_seen=no; \ + target=`echo $@ | sed s/-recursive//`; \ + list='$(SUBDIRS)'; for subdir in $$list; do \ + echo "Making $$target in $$subdir"; \ + if test "$$subdir" = "."; then \ + dot_seen=yes; \ + local_target="$$target-am"; \ + else \ + local_target="$$target"; \ + fi; \ + (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) $$local_target) \ + || eval $$failcom; \ + done; \ + if test "$$dot_seen" = "no"; then \ + $(MAKE) $(AM_MAKEFLAGS) "$$target-am" || exit 1; \ + fi; test -z "$$fail" + +mostlyclean-recursive clean-recursive distclean-recursive \ +maintainer-clean-recursive: + @failcom='exit 1'; \ + for f in x $$MAKEFLAGS; do \ + case $$f in \ + *=* | --[!k]*);; \ + *k*) failcom='fail=yes';; \ + esac; \ + done; \ + dot_seen=no; \ + case "$@" in \ + distclean-* | maintainer-clean-*) list='$(DIST_SUBDIRS)' ;; \ + *) list='$(SUBDIRS)' ;; \ + esac; \ + rev=''; for subdir in $$list; do \ + if test "$$subdir" = "."; then :; else \ + rev="$$subdir $$rev"; \ + fi; \ + done; \ + rev="$$rev ."; \ + target=`echo $@ | sed s/-recursive//`; \ + for subdir in $$rev; do \ + echo "Making $$target in $$subdir"; \ + if test "$$subdir" = "."; then \ + local_target="$$target-am"; \ + else \ + local_target="$$target"; \ + fi; \ + (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) $$local_target) \ + || eval $$failcom; \ + done && test -z "$$fail" +tags-recursive: + list='$(SUBDIRS)'; for subdir in $$list; do \ + test "$$subdir" = . || (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) tags); \ + done +ctags-recursive: + list='$(SUBDIRS)'; for subdir in $$list; do \ + test "$$subdir" = . || (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) ctags); \ + done + +ID: $(HEADERS) $(SOURCES) $(LISP) $(TAGS_FILES) + list='$(SOURCES) $(HEADERS) $(LISP) $(TAGS_FILES)'; \ + unique=`for i in $$list; do \ + if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \ + done | \ + $(AWK) ' { files[$$0] = 1; } \ + END { for (i in files) print i; }'`; \ + mkid -fID $$unique +tags: TAGS + +TAGS: tags-recursive $(HEADERS) $(SOURCES) $(TAGS_DEPENDENCIES) \ + $(TAGS_FILES) $(LISP) + tags=; \ + here=`pwd`; \ + if ($(ETAGS) --etags-include --version) >/dev/null 2>&1; then \ + include_option=--etags-include; \ + empty_fix=.; \ + else \ + include_option=--include; \ + empty_fix=; \ + fi; \ + list='$(SUBDIRS)'; for subdir in $$list; do \ + if test "$$subdir" = .; then :; else \ + test ! -f $$subdir/TAGS || \ + tags="$$tags $$include_option=$$here/$$subdir/TAGS"; \ + fi; \ + done; \ + list='$(SOURCES) $(HEADERS) $(LISP) $(TAGS_FILES)'; \ + unique=`for i in $$list; do \ + if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \ + done | \ + $(AWK) ' { files[$$0] = 1; } \ + END { for (i in files) print i; }'`; \ + if test -z "$(ETAGS_ARGS)$$tags$$unique"; then :; else \ + test -n "$$unique" || unique=$$empty_fix; \ + $(ETAGS) $(ETAGSFLAGS) $(AM_ETAGSFLAGS) $(ETAGS_ARGS) \ + $$tags $$unique; \ + fi +ctags: CTAGS +CTAGS: ctags-recursive $(HEADERS) $(SOURCES) $(TAGS_DEPENDENCIES) \ + $(TAGS_FILES) $(LISP) + tags=; \ + here=`pwd`; \ + list='$(SOURCES) $(HEADERS) $(LISP) $(TAGS_FILES)'; \ + unique=`for i in $$list; do \ + if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \ + done | \ + $(AWK) ' { files[$$0] = 1; } \ + END { for (i in files) print i; }'`; \ + test -z "$(CTAGS_ARGS)$$tags$$unique" \ + || $(CTAGS) $(CTAGSFLAGS) $(AM_CTAGSFLAGS) $(CTAGS_ARGS) \ + $$tags $$unique + +GTAGS: + here=`$(am__cd) $(top_builddir) && pwd` \ + && cd $(top_srcdir) \ + && gtags -i $(GTAGS_ARGS) $$here + +distclean-tags: + -rm -f TAGS ID GTAGS GRTAGS GSYMS GPATH tags + +distdir: $(DISTFILES) + $(mkdir_p) $(distdir)/devdoc + @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's|.|.|g'`; \ + list='$(DISTFILES)'; for file in $$list; do \ + case $$file in \ + $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \ + $(top_srcdir)/*) file=`echo "$$file" | sed "s|^$$topsrcdirstrip/|$(top_builddir)/|"`;; \ + esac; \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + dir=`echo "$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test "$$dir" != "$$file" && test "$$dir" != "."; then \ + dir="/$$dir"; \ + $(mkdir_p) "$(distdir)$$dir"; \ + else \ + dir=''; \ + fi; \ + if test -d $$d/$$file; then \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -pR $(srcdir)/$$file $(distdir)$$dir || exit 1; \ + fi; \ + cp -pR $$d/$$file $(distdir)$$dir || exit 1; \ + else \ + test -f $(distdir)/$$file \ + || cp -p $$d/$$file $(distdir)/$$file \ + || exit 1; \ + fi; \ + done + list='$(DIST_SUBDIRS)'; for subdir in $$list; do \ + if test "$$subdir" = .; then :; else \ + test -d "$(distdir)/$$subdir" \ + || $(mkdir_p) "$(distdir)/$$subdir" \ + || exit 1; \ + distdir=`$(am__cd) $(distdir) && pwd`; \ + top_distdir=`$(am__cd) $(top_distdir) && pwd`; \ + (cd $$subdir && \ + $(MAKE) $(AM_MAKEFLAGS) \ + top_distdir="$$top_distdir" \ + distdir="$$distdir/$$subdir" \ + distdir) \ + || exit 1; \ + fi; \ + done +check-am: all-am +check: check-recursive +all-am: Makefile $(DATA) +installdirs: installdirs-recursive +installdirs-am: + for dir in "$(DESTDIR)$(devdocdir)" "$(DESTDIR)$(pkgdocdir)"; do \ + test -z "$$dir" || $(mkdir_p) "$$dir"; \ + done +install: install-recursive +install-exec: install-exec-recursive +install-data: install-data-recursive +uninstall: uninstall-recursive + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-recursive +install-strip: + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + `test -z '$(STRIP)' || \ + echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install +mostlyclean-generic: + +clean-generic: + -test -z "$(CLEANFILES)" || rm -f $(CLEANFILES) + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." +clean: clean-recursive + +clean-am: clean-generic mostlyclean-am + +distclean: distclean-recursive + -rm -f Makefile +distclean-am: clean-am distclean-generic distclean-tags + +dvi: dvi-recursive + +dvi-am: + +html: html-recursive + +info: info-recursive + +info-am: + +install-data-am: install-dist_devdocDATA install-nodist_pkgdocDATA + +install-exec-am: + +install-info: install-info-recursive + +install-man: + +installcheck-am: + +maintainer-clean: maintainer-clean-recursive + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-generic + +mostlyclean: mostlyclean-recursive + +mostlyclean-am: mostlyclean-generic + +pdf: pdf-recursive + +pdf-am: + +ps: ps-recursive + +ps-am: + +uninstall-am: uninstall-dist_devdocDATA uninstall-info-am \ + uninstall-nodist_pkgdocDATA + +uninstall-info: uninstall-info-recursive + +.PHONY: $(RECURSIVE_TARGETS) CTAGS GTAGS all all-am check check-am \ + clean clean-generic clean-recursive ctags ctags-recursive \ + distclean distclean-generic distclean-recursive distclean-tags \ + distdir dvi dvi-am html html-am info info-am install \ + install-am install-data install-data-am \ + install-dist_devdocDATA install-exec install-exec-am \ + install-info install-info-am install-man \ + install-nodist_pkgdocDATA install-strip installcheck \ + installcheck-am installdirs installdirs-am maintainer-clean \ + maintainer-clean-generic maintainer-clean-recursive \ + mostlyclean mostlyclean-generic mostlyclean-recursive pdf \ + pdf-am ps ps-am tags tags-recursive uninstall uninstall-am \ + uninstall-dist_devdocDATA uninstall-info-am \ + uninstall-nodist_pkgdocDATA + + +.PRECIOUS: $(POD_FILES) + +.pod.in.pod: + $(SUBST) $< > $@ + +@POD2TEXT_PRESENT_TRUE@.pod.txt: +@POD2TEXT_PRESENT_TRUE@ $(POD2TEXT) $< > $@ + +htdocs: $(POD_FILES) + cd manpages; make pods + HTMLDIR=@abs_top_builddir@/../htdocs $(SHELL) mkhtdocs.sh +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/torrus/doc/devdoc/architecture.pod b/torrus/doc/devdoc/architecture.pod new file mode 100644 index 000000000..4cf9c9ccb --- /dev/null +++ b/torrus/doc/devdoc/architecture.pod @@ -0,0 +1,511 @@ +# architecture.pod: The Torrus internals +# Copyright (C) 2002-2005 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: architecture.pod,v 1.1 2010-12-27 00:04:37 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 Torrus Framework Architecture + +=head2 Configuration Processing + +The XML configuration is compiled into the database representation by +operator's manual request. + +The compiled version of configuration is not a one-to-one +representation of the XML version. All aliases and templates are +expanded. The backwards restoration of XML from the database +is available with the snapshot utility. + +Aliases are the way to represent the data in a more convenient format. +An alias can point to a subtree or a leaf, and it works similarly as +a symbolic link in a filesystem. + +A template defines a piece of configuration which can be used in +multiple places. Templates can be nested. + +The configuration can consist of several XML files. They will be +processed in the specified order. Each new file is treated as an additive +information to the existing tree. + +The XML configuration compiler validates all the mandatory parameters. + + +=head2 Database Architecture + +All runtime data is stored in +B<Berkeley DB> database environment (http://www.sleepycat.com). + +The compiled version of the configuration XML is stored in +the B<ds_config_DSINST.db> and B<other_config_OINST.db>. +These databases have similar structure, and +B<ds_config_DSINST.db> keeps all datasource-related information. +C<DSINST> and C<OINST> stand for the productive instance number, +and have values of 0 or 1. +Current productive instance numbers are stored in B<db_config_instances.db> +database. + +For each datasource tree, the database files are resided in +F</var/torrus/db/sub/E<gt>tree_nameE<lt>> directory. + +The runtime modules access the configuration via C<ConfigTree> objects. + +Each datasource subtree or leaf is identified by a I<token>. +A token is a short alphanumeric string, generated internally. +Two types of tokens are recognized: single tokens and token sets. + +Single token starts with letter I<T>. The rest is made with decimal digts. + +Token set name starts with letter I<S>. The rest is an arbitrary sequence of +word characters. + +The special token I<SS> is reserved for tokensets list. Also tokenset +parameters are inherited from this token's parameters. + +View and monitor names must be unique, and must +start with a lower case letter. + +B<db_config_instances.db> is a I<Hash> database, with keys of form +C<ds:E<lt>tree_nameE<gt>> or C<other:E<lt>tree_nameE<gt>>, and 0 or 1 as +values. Also the compiler adds an entry C<compiling:E<lt>tree_nameE<gt>> +during the compilation time, in order to avoid two compiler processes +running at the same time on the same tree. + +B<ds_config_DSINST.db> is a I<Btree> database, with the keys and values +defined as follows: + +=over 4 + +=item * tp:E<lt>pathE<gt> -- E<lt>tokenE<gt> + +Gives the token correspondig to the given element name. + +=item * pt:E<lt>tokenE<gt> -- E<lt>pathE<gt> + +Gives the path name by the given token. + +=item * c:E<lt>tokenE<gt> -- E<lt>ctokenE<gt>,... + +For given subtree, contains the list of child tokens separated by comma. + +=item * p:E<lt>tokenE<gt> -- E<lt>ptokenE<gt> + +For given subtree or leaf, contains the parent token. + +=item * P:E<lt>tokenE<gt>:E<lt>pnameE<gt> -- E<lt>valueE<gt> + +Contains the parameter value for specified leaf or subtree. +Each leaf or subtree inherits parameters from its parent. +Thus, we must climb up the tree in order to get the parameter's +value if not defined locally. + +=item * Pl:E<lt>tokenE<gt> -- E<lt>pnameE<gt>,... + +Contains the list of parameter names for specified leaf or subtree. + +=item * a:E<lt>tokenE<gt> -- E<lt>tokenE<gt> + +If this subtree or leaf is an alias, specifies the reference to the real node. + +=item * ar:E<lt>tokenE<gt> -- E<lt>tokenE<gt>,... + +Specifies all alias subtrees or leaves pointing to this token. + +=item * d:E<lt>nameE<gt> -- E<lt>valueE<gt> + +Definition value for the given name + +=item * D: -- E<lt>nameE<gt>,E<lt>nameE<gt>,... + +List of all known definitions + +=item * n:E<lt>tokenE<gt> -- E<lt>typeE<gt> + +Defines a node type. Type is a number with the following values: +0 for subtree, 1 for leaf, 2 for alias. + +=back + +B<other_config_OINST.db> is a I<Btree> database, with the keys and values +defined as follows: + +=over 4 + +=item * ConfigurationReady -- 1:0 + +When nonzero, the configuration is ready for usage. +Otherwise, the configuration status is undefined. + +=item * P:E<lt>nameE<gt>:E<lt>pnameE<gt> -- E<lt>valueE<gt> + +Contains the parameter value for specified view, monitor or action. + +=item * Pl:E<lt>nameE<gt> -- E<lt>pnameE<gt>,... + +Contains the list of parameter names for specified view, +monitor, or action. + +=item * V: -- E<lt>vnameE<gt>,... + +Specifies comma-separated list of all views defined. + +=item * v:E<lt>tokenE<gt> -- E<lt>vnameE<gt>,... + +Specifies comma-separated list of view names for the path given. +The first view in the list is interpreted as default. + +=item * M: -- E<lt>mnameE<gt>,... + +Specifies comma-separated list of all monitor names defined + +=item * A: -- E<lt>anameE<gt>,... + +Comma-separated list of actions defined + +=back + + + + +B<paramprops_DSINST.db> is a I<Btree> database for storing the +datasource parameter properties, such as expandable, list parameters, +searchable, etc.: + +=over 4 + +=item * E<lt>pnameE<gt>:E<lt>propertyE<gt> -- E<lt>valueE<gt> + +=back + + + + + +B<aliases_DSINST.db> is a I<Btree> database with alias paths as keys +and target tokens as values. It is used for quick alias expansion. + +B<tokensets_DSINST.db> is a I<Hash> database containing the token sets. +The keys and values are as follows: + +=over 4 + +=item * S: -- E<lt>tokensetE<gt>,... + +Keeps the list of all known token sets. + +=item * s:E<lt>tokensetE<gt> -- E<lt>tokenE<gt>,... + +For given tokenset, keeps its contents. + +=item * o:E<lt>tokensetE<gt>:E<lt>tokenE<gt> -- E<lt>originE<gt> + +Defines the origin of the member. Currently two types of origin are known: +C<static> and C<monitor> + +=back + +B<nodepcache_DSINST.db> is a I<Btree> database containing the cached +node parameter values. The keys and values are as follows: + +=over 4 + +=item * E<lt>nameE<gt>:E<lt>pnameE<gt> -- E<lt>statusE<gt>E<lt>valueE<gt> + +Keeps the status and the value for a given token and parameter. +Status is a one-byte prefix, with values C<U> for undefined parameter, and +C<D> for a parameter with value. + +=back + + +B<nodeid_DSINST.db> is a I<Btree> database that stores the mapping between +NodeID values and tokens. Database keys are NodeID strings, and values +are tokens. One NodeID corresponds to maximum one token. + + + +B<config_readers.db> is a I<Hash> database which contains the informaton +about active processes which read the configuration. The configuration +compiler waits until all readers finish using the current configuration +database. Process IDs are used as keys, and the values contain timestamps. + +B<timestamps.db> is a I<Hash> database containing various kinds of +timestamps. The timestamp name is the key, and the number of seconds +since epoch is the value. + +B<render_cache.db> keeps the status information about the graphs +ready to display. Last known timestamp of the configuration is +compared with the actual one. When the actual timestamp +differs from known, the renderer cache is cleaned up. +This is a I<Hash> database, with the following +keys and values: + +=over 4 + +=item * E<lt>tokenE<gt>:E<lt>vnameE<gt> -- + E<lt>t_renderE<gt>:E<lt>t_expiresE<gt>:E<lt>filenameE<gt>:E<lt>mime_typeE<gt> + +For the leaf/subtree and view name given, specifies two timestamps: the +moment of last rendering and expiration time. The filename is automatically +generated unique name in the spool directory. The contents type is determined +by the MIME type. + +=back + +B<monitor_cache.db> is a I<Hash> database used in order to avoid the +unneccessary configuration tree walk. The keys are the leaf tokens, and +the values are comma-separated monitor names. At each monitor invocation, +the confguration timestamp is compared against the last known, and the +cache database is rebuilt if needed. + +B<monitor_alarms.db> is a I<Hash> database that keeps alarm status information +from previous runs of Monitor, with the keys and values as follows: + +=over 4 + +=item * E<lt>mnameE<gt>:E<lt>pathE<gt> -- +E<lt>t_setE<gt>:E<lt>t_expiresE<gt>:E<lt>statusE<gt>: +E<lt>t_last_changeE<gt> + +Key consists of the monitor name and leaf path. In the value, B<t_set> +is the time when the alarm was raised. If two subsequent runs of Monitor +raise the same alarm, B<t_set> does not change. B<t_expires> is the +timestamp that shows when it's still important to keep the entry after the +alarm is cleared. B<status> is 1 if the alarm is active, and 0 otherwise. +B<t_last_change> is the timestamp of last status change. + +When B<status> is 1, the record is kept regardless of timestamps. +When B<status> is 0, and the current time is more than B<t_expires>, +the record is not reliable and may be deleted by Monitor. + +=back + +B<collector_tokens_X_Y.db> is a I<Hash> database used in order to avoid the +unneccessary configuration tree walk. X is the collector instance number, and +Y is the datasource configuration instance number. +Keys and values are as follows: + +=over 4 + +=item * E<lt>tokenE<gt> -- E<lt>periodE<gt>:E<lt>offsetE<gt> + +For each leaf token, period and time offset values are stored. + +=back + + +B<scheduler_stats.db> is a I<Btree> database which stores the runtime +statistics of Scheduler tasks. Each key is of structure +B<E<lt>tasknameE<gt>:E<lt>periodE<gt>:E<lt>offsetE<gt>:E<lt>variableE<gt>>, +and the value is a number representing the current value of the variable. +Depending on variable purpose, the number is floating point or integer. + + +B<users.db> is a I<Hash> database containing user details, passwords, +and group membership: + +=over 4 + +=item * ua:E<lt>uidE<gt>:E<lt>attrE<gt> -- E<lt>valueE<gt> + +User attributes, such as C<cn> (Common name) or C<userPassword>, are stored +here. For each user, there is a record consisting of the attribute C<uid>, +with the value equal to the user identifier. + +=item * uA:E<lt>uidE<gt> -- E<lt>attrE<gt>, ... + +Comma-separated list of attribute names for the given user. + +=item * gm:E<lt>uidE<gt> -- E<lt>groupE<gt>, ... + +For each user ID, stores the comma-separated list of groups it belongs to. + +=item * ga:E<lt>groupE<gt>:E<lt>attrE<gt> -- E<lt>valueE<gt> + +Group attributes, such as group description. + +=item * gA:E<lt>groupE<gt> -- E<lt>attrE<gt>, ... + +Comma-separated list of attribute names for the given group. + +=item * G: -- E<lt>groupE<gt>, ... + +List of all groups + +=back + + +B<acl.db> is a I<Hash> database containing group privileges information: + +=over 4 + +=item * u:E<lt>groupE<gt>:E<lt>objectE<gt>:E<lt>privilegeE<gt> -- 1 + +The entry exists if and only if the group members have this privilege +over the object given. Most common privilege is C<DisplayTree>, where +the object is the tree name. + +=back + + +B<serviceid_params.db> is a I<Btree> database containing properties +for each Service ID (exported collector information, usually stored in +an SQL database): + +=over 4 + +=item * a: E<lt>serviceidE<gt>,... + +Lists all known service IDs + +=item * t:E<lt>treeE<gt> -- E<lt>serviceidE<gt>,... + +Lists service IDs exported by a given datasource tree. + +=item * p:E<lt>serviceidE<gt>:E<lt>paramE<gt> -- E<lt>valueE<gt> + +Parameter value for a given service ID. Mandatory parameters are: +C<tree>, C<token>, C<dstype>. Optional: C<units>. + +=item * P:E<lt>serviceidE<gt> -- E<lt>paramE<gt>, ... + +List of parameter names for a service ID. + +=back + + +B<searchwords.db> is a I<Btree> database with DB_DUP and DB_DUPSORT flags. +It contains the search strings for the given tree: + +=over 4 + +=item * E<lt>keywordE<gt> -- E<lt>pathE<gt>[:E<lt>paramE<gt>] + +For a given keyword, refer to a path of a node that contains this word. +If the node name matches the keyword, the I<param> element +is omitted. Otherwise it refers to the parameter that matches the keyword. + +=back + + + +B<globsearchwords.db> is a I<Btree> database with DB_DUP and DB_DUPSORT flags. +It contains the search strings for all trees: + +=over 4 + +=item * E<lt>keywordE<gt> -- E<lt>treeE<gt>:E<lt>pathE<gt>[:E<lt>paramE<gt>] + +For a given keyword, refer to a path of a node that contains this word. +If the node name matches the keyword, the I<param> element +is omitted. Otherwise it refers to the parameter that matches the keyword. + +=back + + +B<snmp_failures_X.db> is a I<Btree> database containing SNMP collector +failures information for a given collector instance for a tree. + +=over 4 + +=item * c:E<lt>counterE<gt> -- E<lt>NE<gt> + +A counter with a name. Known names: I<unreachable>, I<removed>. + + +=item * h:E<lt>hosthashE<gt> -- E<lt>failureE<gt>:E<lt>timestampE<gt> + +SNMP host failure information. Hosthash is a concatenation of hostname, UDP +port, and SNMP community, separated by "|". Known failures: I<unreachable>, +I<removed>. Timestamp is a UNIX time of the event. + +=item * m:E<lt>hosthashE<gt> -- E<lt>pathE<gt>:E<lt>timestampE<gt> + +MIB failures (I<noSuchObject>, I<noSuchInstance>, and I<endOfMibView>) +for a given host, with the tree path of their occurence and the UNIX timestamp. + +=item * M:E<lt>hosthashE<gt> -- E<lt>NE<gt> + +Count of MIB failures per SNMP host. + +=back + + + + + + + +=head2 Modular Structure + +The Torrus framework consists of several functional modules: + +=over 4 + +=item * Configuration management + +Once the configuration XML files get changed, the configuration compiler +should be run manually. This guarantees that the actual framework +configuration is changed only when the files are ready. + +The configuration management module provides access methods for +enumeration and enquery of the configuratin objects. + +=item * Data Collector module + +Collector program runs as a separate process for each datasource tree. +Upon startup, it first runs all registered collectors. After that, +the collectors are grouped depending on period and time offset, and launched +periodically at the moments defined by formula: + + time + period - (time mod period) + timeoffset + +The datasources are grouped by collector type. +For SNMP collector type, the datasources are grouped by host. +SNMP requests are sent in non-blocking mode (see Net::SNMP Perl module +manual). + +For each SNMP host, system uptime is verified. For RRD datasource types +"COUNTER", if the device reload is +detected, the corresponding RRD file is updated with "undefined" +value at the calculated moment of reload. + +=item * Data threshold monitoring + +This module performs the monitoring tasks periodically, based on each +monitored leaf schedule. +It checks the conditions for each leaf having a monitor. +In case of the alarm, it executes the action instructions synchronously. + +=item * Rendering module + +Upon a request, this module generates the graph and HTML files for the +requested view and its subviews. It first checks availability of +cached objects and avoids unneeded regeneration. It must be possible +to force the renderer to flush the cache. + +=item * Web interface module + +Web interface module passes the Renderer output to an HTTP client. + + +=back + +=head1 Author + +Copyright (c) 2002-2005 Stanislav Sinyagin ssinyagin@yahoo.com diff --git a/torrus/doc/devdoc/devdiscover.pod b/torrus/doc/devdoc/devdiscover.pod new file mode 100644 index 000000000..8386c1755 --- /dev/null +++ b/torrus/doc/devdoc/devdiscover.pod @@ -0,0 +1,296 @@ +# devdiscover.pod - Guide to devdiscover +# Copyright (C) 2003 Shawn Ferry, Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: devdiscover.pod,v 1.1 2010-12-27 00:04:36 ivan Exp $ +# Shawn Ferry <sferry at sevenspace dot com> <lalartu at obscure dot org> +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# + +=head1 Torrus SNMP Device Discovery Developer's Guide + +=head2 C<devdiscover> overview + +C<devdiscover> is an extensible, module based, SNMP device discovery +utility. It is intended to automatically generate Torrus configuration +files, based on SNMP discovery results and templates. + +See I<Torrus Command Reference> for command usage and functionality overview. + +In general, C<devdiscover> consists of the following files and functional +parts: + +=over 4 + +=item * C<bin/devdiscover.in> + +This file is installed as C<bin/devdiscover> in Torrus installation directory, +with certain variables substituted. The program provides all the commandline +functionality and options processing. Once the CLI options are processed and +verified, the control is passed to the C<Torrus::DevDiscover> object. + +=item * C<Torrus::DevDiscover> + +This Perl module is responsible for the SNMP discovery process organization: + +=over 8 + +=item * + +it registers the discovery modules; + +=item * + +establishes an SNMP session to the target host; + +=item * + +initiates a new C<Torrus::DevDiscover::DevDetails> object for the target host; + +=item * + +stores the connection-specific parameters to the device object; + +=item * + +for each registered discovery module, executes C<checkdevtype()> in +I<sequential> order; + +=item * + +for those discovery modules which paid interest in this target host, +executes C<discover()> in I<sequential> order; + +=item * + +upon request from C<bin/devdiscover>, builds the configuration +XML tree, by calling C<buildConfig()> in I<sequential> order for each +relevant discovery module for each target host. + +=back + +=item * C<Torrus::DevDiscover::DevDetails> + +This Perl module is defined in F<perllib/Torrus/DevDiscover.pm>, and provides +the functionality to store the results of SNMP device discovery. + +=item * C<Torrus::ConfigBuilder> + +This module is an encapsulation wrapper for XML configuration builder. +It provides methods for every element of Torrus configuration. + +=item * Discovery Modules + +These provide all the functionality for SNMP discovery. Normally +one module covers one MIB, or sometimes several vendor-specific MIBs, +and it is responsible for finding out the device details necessary +for Torrus configuration building. Usually a discovery module refers to one or +several I<template definition files>. A module may depend on +other modules' discovery results. This is controlled by its +C<sequence number>. Vendor-independent discovery modules are normally named +as C<Torrus::DevDiscover::RFCXXXX_SOME_HUMAN_NAME>, and vendor-specific +ones are named as C<Torrus::DevDiscover::Vendor[Product[Subsystem]]>. + +=item * Template definition files + +These are XML documents residing in F<xmlconfig/vendor> and +F<xmlconfig/generic> directories. Each file is a piece of Torrus configuration, +and contains definitions and templates for particular MIB or vendor. +Generic template definition files are for vendor-independent MIBs, +and normally they are named as F<rfcXXXX.some-human-name.xml>. +Vendor-specific files are named as F<vendor.product[.subsystem].xml>. + +=back + + +=head2 Discovery Module Internals + +Discovery modules are Perl packages with few required components. +Before creating your own modules, please read and follow +I<Torrus Programming Style Guide>. + +Upon initialization, C<Torrus::DevDiscover> loads the modules listed in +C<@Torrus::DevDiscover::loadModules> array. This array is pre-populated +by standard module names in F<devdiscover-config.pl>. +You can add new module names by pushing them onto this array in your +local F<devdiscover-siteconfig.pl>. + +=head3 Module Registration + +Each discovery module should register itself in DevDiscover registry. +Normally there's only one registry entry per discovery module, though +it's not a limitation. The registry entry is identified by a registry +name, which normally repeats the module name. + +Example: + + $Torrus::DevDiscover::registry{'RFC2790_HOST_RESOURCES'} = { + 'sequence' => 100, + 'checkdevtype' => \&checkdevtype, + 'discover' => \&discover, + 'buildConfig' => \&buildConfig + }; + +Each registry entry must contain 4 fields: + +=over 4 + +=item * C<sequence> + +The sequence number determines the order in which every discovery module's +procedure is executed. Sequence numbers of dependant modules must +be higher than those of their dependencies. + +Generic MIB discovery modules should have the sequence number 100. If +a particular generic module depends on other generic modules, its sequence +number may be 110. + +Vendor-specific modules should have the sequence number 500. +Vendor-specific modules that depend on other vendor-specific modules, +should have sequence number 510. + +Dependencies deeper than one level may exist, but it's recommended +to avoid them. For most cases this should be enough. + +Exception is made for C<RFC2863_IF_MIB> module, which has the sequence +number 50. That is because it provides the basic interface discovery, +and many other modules depend on its results. + +Another exception is vendor-specific modules where the SNMP session parameters +must be set earliest possible. One of such parameters is C<snmp-max-msg-size>. +Some vendor SNMP agents would not be walked properly without this setting. +In these occasions, the sequence number is below 50. The recommended value +is 30. + +=item * C<checkdevtype> + +Must be a subroutine reference. This subroutine is called with two object +references as arguments: C<Torrus::DevDiscover> and +C<Torrus::DevDiscover::DevDetails>. +The purpose of this subroutine is to determine if the target host is +of required type, or if it supports the required MIB. +The subroutine should return true if and only if the target host +supports the MIB variables this module is supposed to discover. + +In general, C<checkdevtype> subroutine is small, and checks one or several +OIDs presence on the host, or their values, e.g. the value of I<sysObjectID> +variable. It should perform as less as possible SNMP requests, in order to +speed up the pre-discovery process. + +=item * C<discover> + +Must be a subroutine reference. This subroutine is called with the same +two arguments as C<checkdevtype()>. It is called for those modules only, +whose C<checkdevtype()> has returned true. The subroutine should return true +if no errors occured during the discovery. + +The purpose of C<discover()> is to perform the actual SNMP discovery, +and prepare the parameter values for future XML configuration. + +=item * C<buildConfig> + +Must be a subroutine reference. This subroutine is called with three object +references as arguments: C<Torrus::DevDiscover::DevDetails>, +C<Torrus::ConfigBuilder>, and an XML element object, which should be used only +to pass data to ConfigBuilder methods. + +This subroutine is designed to construct the resulting XML configuration +subtree as a child of a given XML element. Upper level subtrees +are handled by CLI options processing code. + +=back + + +=head3 OID Definitions + +OID definitions are designed to provide symbolic names to OIDs +in numerical notation. Normally the symbolic names repeat the names from +corresponding MIBs. + +The definitions must be defined in an C<oiddef> hash defined in the +package namespace. Then they are automatically imported by DevDiscover +initialization procerure. + +Example: + + our %oiddef = + ( + 'hrSystemUptime' => '1.3.6.1.2.1.25.1.1.0', + 'hrSystemNumUsers' => '1.3.6.1.2.1.25.1.5.0', + 'hrSystemProcesses' => '1.3.6.1.2.1.25.1.6.0', + 'hrSystemMaxProcesses' => '1.3.6.1.2.1.25.1.7.0', + 'hrMemorySize' => '1.3.6.1.2.1.25.2.2.0', + 'hrStorageTable' => '1.3.6.1.2.1.25.2.3.1', + 'hrStorageIndex' => '1.3.6.1.2.1.25.2.3.1.1', + 'hrStorageType' => '1.3.6.1.2.1.25.2.3.1.2', + 'hrStorageDescr' => '1.3.6.1.2.1.25.2.3.1.3', + 'hrStorageAllocationUnits' => '1.3.6.1.2.1.25.2.3.1.4', + 'hrStorageSize' => '1.3.6.1.2.1.25.2.3.1.5', + 'hrStorageUsed' => '1.3.6.1.2.1.25.2.3.1.6', + 'hrStorageAllocationFailures' => '1.3.6.1.2.1.25.2.3.1.7' + ); + + +=head3 Template References + +Normally a discovery module would refer to configuration templates +defined in template definition files. In order to provide an extra level of +flexibility, these templates should be defined in +F<devdiscover-config.pl> or in F<devdiscover-siteconfig.pl>. + +It is recommended that the template references in the discovery modules +follow the naming standard: C<module::template-name>. + +ConfigBuilder's C<addTemplateApplication()> method looks up every +template name in the global hash C<%Torrus::ConfigBuilder::templateRegistry> +and figures out the source XML file and the actual template name. + +Example: + + $Torrus::ConfigBuilder::templateRegistry{ + 'RFC2790_HOST_RESOURCES::hr-system-uptime'} = { + 'name' => 'mytest-hr-system-uptime', + 'source' => 'mytest.templates.xml' + }; + + +=head3 Interface filtering + +Usually not all interfaces from ifTable need to be monitored. +For example, Loopback and Null0 interfaces on Cisco routers. + +C<Torrus::DevDiscover::RFC2863_IF_MIB> provides the functionality to +automatically filter out the interfaces, based on filter definitions. +Filter definitions are registered by calling the subroutine +C<Torrus::DevDiscover::RFC2863_IF_MIB::addInterfaceFilter +($devdetails, $interfaceFilter)>. The second argument is a reference +to a hash of the following structure: + +Keys are symbolic names that mean nothing and need only to be unique. +Values are hash references with the following entries: C<ifType> +specifies the IANA interface type, and optional C<ifDescr> specifies +a regular expression to match against interface description. + +The filters are usually registered within C<checkdevtype> subroutine +of the vendor module, after the device type is identified. See +F<CiscoIOS.pm> and F<CiscoCatOS.pm> as examples. + + +=head2 Authors + +Shawn Ferry: initial draft. + +Stanislav Sinyagin: revision and detailed content. diff --git a/torrus/doc/devdoc/progstyle.pod b/torrus/doc/devdoc/progstyle.pod new file mode 100644 index 000000000..e9ebef58a --- /dev/null +++ b/torrus/doc/devdoc/progstyle.pod @@ -0,0 +1,138 @@ +# rpnexpr.pod - Torrus RPN expressions guide +# Copyright (C) 2002 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: progstyle.pod,v 1.1 2010-12-27 00:04:37 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 Torrus Programming Style Guide + +=head2 Perl indentation style + +The code indentation style is a kind of BSD/Allman style: + + while( not $success and time() < $waitingTimeout ) + { + $self->clearReader(); + + Info('Sleeping ' . $Torrus::Global::ConfigReadyRetryPeriod . + ' seconds'); + sleep $Torrus::Global::ConfigReadyRetryPeriod; + + $self->setReader(); + + if( $self->isReady() ) + { + $success = 1; + Info('Now configuration is ready'); + } + else + { + Info('Configuration is still not ready'); + } + } + + +Indentation is 4 characters. Opening and closing braces are aligned. +There's no space between the keyword (C<while>, C<if>, etc.) and the opening +parenthesis. + +Tab characters are prohibited. + +Page width is strictly 80 characters. All longer lines must be wrapped. + +When possible, leave space between parentheses and the inside content. +This is not necessary for debug or print statements. + +There's always space around the equal sign (C<=>). + +The object method calls always have parentheses, even if no arguments are +reqiured. + +Use keywords for logical operations instead of C operators: C<and>, C<or>, +C<not>. + +Use single quotes in hash references: C<$a-E<gt>{'abc'}>. + +=head2 Common file properties + +With the exception of special-purpose files, each source file +must ontain the GNU copying statement, CVS C<Id> tag, and author's name and +e-mail address. + +C, Perl, and Bourne shell files must contain Gnu Emacs variables +at the end of the file: + + # Local Variables: + # mode: perl + # indent-tabs-mode: nil + # perl-indent-level: 4 + # End: + +Each file must always end with the linebreak. Otherwise it might conflict +with CVS. All files must have Unix linebreak format. + +=head2 GNU Emacs settings + +Standard C<perl-mode.el> does the thing: + + ;; Set up Perl mode + (autoload 'perl-mode "perl-mode") + (setq auto-mode-alist + (append (list (cons "\\.pl$" 'perl-mode) + (cons "\\.pm$" 'perl-mode) + (cons "\\.pl\\.cgi$" 'perl-mode)) + auto-mode-alist)) + + (custom-set-variables + ;; custom-set-variables was added by Custom -- don't edit or cut/paste it! + ;; Your init file should contain only one such instance. + '(indent-tabs-mode nil) + '(tab-width 8) + ) + +=head2 X-Emacs settings + +In X-Emacs, the default handler for Perl files is C<cperl-mode.el>. +The following custom variables must be set in order to comply to our styling +standards: + + (custom-set-variables + ;; custom-set-variables was added by Custom -- don't edit or cut/paste it! + ;; Your init file should contain only one such instance. + '(cperl-brace-offset -4) + '(cperl-continued-statement-offset 4) + '(cperl-indent-level 4) + '(indent-tabs-mode nil) + '(tab-width 8) + ) + +=head2 Normalizing multiple files + +In Torrus CVS repository, in the root of module C<src>, there is a small +utility that fixes some styling issues for all the sources in +current directory and subdirectories: + + perl normalize-all-sources.pl + +It replaces tabs with spaces, deletes space at the end of line, +and removes empty lines at the start and the end of file. + +=head1 Author + +Copyright (c) 2003-2005 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> diff --git a/torrus/doc/devdoc/reqs.0.0.pod b/torrus/doc/devdoc/reqs.0.0.pod new file mode 100644 index 000000000..7ed9511bc --- /dev/null +++ b/torrus/doc/devdoc/reqs.0.0.pod @@ -0,0 +1,166 @@ +# requirements.pod: The pre-planning document +# Copyright (C) 2002 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: reqs.0.0.pod,v 1.1 2010-12-27 00:04:36 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 RRD Framework Requirements Version 0.0 + +Date: Jul 10 2002 + +This article defines some principles that a supposedly future +RRD framework should have. The framework should consist of 3 +independent subsystems: + +=over 4 + +=item Data Collection + +=item Data Monitoring + +=item Data Displaying + +=back + +=head2 Flexible Hierarchical Configuration + +Inspired by Cricket hierarchical configuration, we state here that +the configuration should be hierarchical. Child nodes should +inherit the properties from parents. + +The format of the configuration files has not to be neccessary +as in Cricket. I'm not sure if it's worth keeping them in a directory +structure representing the hierarchy tree, but it's definitive +that multiple files should be supported. + +A good step ahead would be the configuration in XML format. +It is also possible to have a converter from some other formats +(plain text, or an SQL database) into XML which will be consumed by the +framework. + +I leave the Data collection uncovered, since all of the existing +RRD frontends do this part already. + +=head1 Data Monitoring Principles + +At the moment, the only known solution for RRD data monitoring is +Cricket. Its threshold monitoring has certain limitation and drawbacks. +Nevertheless, it may be used as the basis for the ideas in the further +development. + +The major idea is to build data monitoring as a part of a bigger RRD +framework, still being the independent part of the whole. The data can come +from many differet sources, from RRDs produced by any of the existing +and future frontends. + +=head2 File Naming Flexibility + +In most existing RRD frontends, each RRD datafile should be described +individually. This is not very convenient, especially for the cases +when you have several (dozens) files containing one type of data. +(e.g., input traffic per source autonomous system). +Also the files of same type can be created and deleted by their sourcing +frontend, and it would be more convenient not having to change +the monitoring configuration. + +Thus, we need a wildcards language which would allow to specify +multiple files and derive the datasource names from thir names. + +=head2 Datasource Naming + +Each data being monitored (for RRDs, its definition specifies the +E<lt>filename, DS, RRAE<gt> triple) has to have a universal name. +The name can be fully or partly qualified, depending on the +configuration tree. Examples of such data reference follow: + + /Netflow/Exporters/63.2.3.224/if3/bps /* Interface #3 on router 63.2.3.224 */ + /Netflow/Subnets/Dialin/bps /* Dial-in address pool */ + /* different grouping for the rack temperature in Server Room 1 */ + /Envmon/RackTemp/SR1 + /SR1/Envmon/RackTemp + +Name aliasing should allow short or symbolic names for data sources: + + /* Alias for /Netflow/Exporters/63.2.3.224/if3 */ + /Netflow/Upstream/FranceTelecom1 + +=head2 Monitoring Rules + +Data threshold monitoring should be described in a hierarchical +manner. + +It would be interesting to have monitoring rules separate from +the data hierarchy. On the other hand, 1) some data sources might need +special and unique monitoring rules; 2) in some cases, several +data sources need to be combined in order to build a threshold rule. +I'm not yet sure how this must be achieved. + +=head2 Event Processing + +Once the threshold violation occurs, the monitoring system +should produce the alarm event. + +Cricket has a good set of ways to report the alarm, and they can be taken +as the basis. + +Also what Cricket is really missing, is displaying those data sources +being alarmed. The Monitoring system should produce the instructions +to the Displaying system in order to display the summary of those +data sources which produce alarms within certain time. + + +=head1 Data Displaying Principles + +View profiles should be configured in a hierarchical manner. + +Again as with data monitoring, some Views should be configured independently +of the data hierarchy, but also some data should be able to define +specific view profiles. + +There should be view profiles of different types: + +=over 4 + +=item * + +HTML Framework. Defines the HTML elements that should be displayed around +the graphs. It also should define the child graphs. Also it should define +the controls which would cause the option changes in the child graphs +(e.g., enabling "Show Holt-Winters Boundaries" would produce the +corresponding graph). + +=item * + +Individual Graph. Defines the way the graph should look. It should +also be capable of displaying an arbitrary number of data sources. +It should have tunable options, like color, size, or time period. + +=back + +The Displaying system should allow the following ways of viewing: +1) hierarchical browsing, like Cricket; 2) alarm summary display; +3) individual graph display, without HTML surrounding. + +The graph images should be cashed and reused whenever possible. +In alarm summary browsing, these images can be generated at the moment +of the event. + +=head1 Author + +Copyright (c) 2002 Stanislav Sinyagin ssinyagin@yahoo.com diff --git a/torrus/doc/devdoc/reqs.0.1.pod b/torrus/doc/devdoc/reqs.0.1.pod new file mode 100644 index 000000000..49698d370 --- /dev/null +++ b/torrus/doc/devdoc/reqs.0.1.pod @@ -0,0 +1,210 @@ +# requirements.pod: The pre-planning document +# Copyright (C) 2002 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: reqs.0.1.pod,v 1.1 2010-12-27 00:04:36 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 RRFW Requirements Version 0.1 + +Date: Jun 29 2003; Last revised: Aug 05 2003 + +In this article, I describe the important changes that are planned +for RRFW version 0.1.X. + +=head1 Independent datasource trees + +As noted by many users, RRFW lacks the scalability when the number of +network devices is more than 100. The XML compiler takes minutes to +process the configuration, and the Collector process initialization time +is too long. + +Christian Schnidrig E<lt>christian.schnidrig@gmx.chE<gt> has proposed +a solution to split the database into several subsystems, each +being compiled separately, and with separate collector process. +In his concept, there is a "global" datasource tree, and +"subsystem" trees, each making a subset of global datasource nodes. + +I propose to have a number of independent datasource trees, without +any superset. This would ease the administrator's work, and add more +security. + +=head2 Changes in rrfw-siteconfig.pl + +Instead of C<@RRFW::Global::xmlFiles>, the following hash will contain +the information about the trees: + + %RRFW::Global::treeConfig = ( + 'tree_A' => { + 'description' => 'The First Tree', + 'xmlfiles' => ['a1.xml', 'a2.xml', 'a3.xml'], + 'run' => { 'collector' => 1, 'monitor' => 1 } }, + 'tree_B' => { + 'description' => 'The Second Tree', + 'xmlfiles' => ['b1.xml', 'b2.xml'], + 'run' => {} } + ); + +In this hash, the keys give the tree names, I<xmlfiles> points to an array +of source XML files, I<run> points to the names of the daemons that +would be automatically launched for the tree. + +Two additional arrays: C<@RRFW::Global::xmlAlwaysIncludeFirst> and +C<@RRFW::Global::xmlAlwaysIncludeLast> will give a list of source XML +files that are included in every tree, in the beginning or in the end of +the XML files list. + +=head2 ConfigTree object internals + +There will be no such thing as globalInstance. All methods and procedures +that need to reference the current ConfigTree object will have it as +argument. + +C<RRFW::ConfigTree::new()> will have a mandatory argument "TreeName". + +=head2 Database structure + +All datasource trees will share one BerkeleyDB environment. The +BDB environment home directory will stay the same, defined by I<dbhome> +config variable. + +For each tree, the database files will be placed in a separate subdirectory +of a subdirectory of I<dbhome>. + + +=head2 User interface + +All relevant command-line executables will support the following +options: + +=over 4 + +=item * --tree <tree_name> + +Specifies the datasource tree for processing; + +=item * --all + +If applicable, performs the operation on all available trees. + +=back + +When in verbose mode (B<--verbose>), the command-line programs must +print the tree names they operate with. + +The web interface will take the PATH_INFO string as the tree name. +For mod_perl handler, it will be also possible to prohibit +PATH_INFO selection, and to configure the tree name in Apache +configuration. + +When no PATH_INFO is given to the web interface handler, +a special superlevel menu may be shown with the list of available trees. + +It will also be possible to specify tree-specific renderer attributes, like +C<%RRFW::Renderer::styling>, C<$RRFW::Renderer::companyName>, etc. + +B<Plain CGI interface will not be supported> As Renderer gets more complex, +CGI initialization time will increase. Also it will become harder to support +two user interfaces with similar functionality. + + +=head2 Daemons launch master + +There will be a master process that will launch collector and monitor +daemons for each tree. It will be configurable from a separate file, +specifying the daemons and execution parameters for each tree. + +The master process will watch the child processes and issue warnings in the +events of child process termination. + +Stopping the master process will stop all child daemons gracefully. + + +=head1 Separate database for non-datasource objects + +In RRFW version 0.0.X, all the parameters for datasources, views, +monitors, and tokensets are stored in F<configuration.db> database. + +As proposed by Christian Schnidrig, storing all non-datasource +objects information in a separate database would improve the scalability. + +In RRFW version 0.1.X, datasource parameters will be stored in +F<ds_config.db>, and all other object's parameters in F<other_config.db>. + +The XML compiler will have a new option, B<--nods>, which disables +processing of E<lt>datasourcesE<gt> elements in the input XML files. + +In addition to C<ConfigurationReady> flag, there will be a flag that indicates +the readiness of datasource tree only. + +All these measures will allow faster administration and testing of +non-datasource objects, and will prevent the collector from unneeded +interruptions. + + +=head1 User privileges + +User privileges will apply to the tree level: across one datasource tree +a given user will have uniform privileges. + +Each user belongs to one or more groups. Privileges are assigned to +groups only, not to individual users. Groups are one-level deep: they +consist of users only. Probably in the future groups will consist +of groups too. + +In the beginning, only one privilege will be implemented: I<DisplayTree>. +The design should be flexible enough to add more privileges in the future. +Examples: I<GenerateReport>, I<Debug>, I<ScheduleTask>, and so on. + +Privileges maintenance interface will include a command-line utility. +In the future, a web interface is also possible. In this case, a new +privilege will be added: I<EditPrivileges>. + +Privileges editor will include the following functions: + +=over 4 + +=item * add/delete group + +=item * add/delete user + +=item * change user password + +=item * add/delete user membership in a group + +=item * edit privileges for groups and trees + +=item * list group members + +=item * list groups a user belongs to + +=item * list privileges for a given group or user + +=item * list privileges and groups (or users) for a given tree + +=item * export/import the privileges database to/from XML + +=back + +Privileges logics implementation must be separate from the database backend. +At first, BerkeleyDB backend will be supported. In the future, LDAP +backend is possible. + +=head1 Author + +Copyright (c) 2003 Stanislav Sinyagin ssinyagin@yahoo.com diff --git a/torrus/doc/devdoc/torrus_roadmap.pod b/torrus/doc/devdoc/torrus_roadmap.pod new file mode 100644 index 000000000..85698f2c8 --- /dev/null +++ b/torrus/doc/devdoc/torrus_roadmap.pod @@ -0,0 +1,249 @@ +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: torrus_roadmap.pod,v 1.1 2010-12-27 00:04:36 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# + +=head1 RRFW to Torrus transition roadmap + +=head2 Introduction + +The name "RRFW" appeared to be quite difficult to remember and to pronounce. +There has been a call for a new name, and recently a good suggestion came +from Francois Mikus: + + --- Francois Mikus <fmikus[at]acktomic.com> wrote: + > Here is my humble flash, which I think may be appropriate. Which I will + > explain why below... + > + > The name I would suggest is; + > + > Torrus + > + > Has a mythical sounding name without the actual history. Has a resonance + > with Torrent, where rrfw deals with a torrent of information. A google + > search comes up with near nothing, and nothing commercial. Has a + > resonance with Taurus, which is mythical, astrological and has an + > underlying strength connotation. + > + > Anyway, this is the best I could think of. And it provides an opening to + > have a semi-mythical/comic style yet serious mascot. + > + > You have a LOT of documentation. web pages, code, etc.. But marketing is + > the way to win hearts and minds, create a following and get rabid + > developpers on-board! + +Thus the project will be renamed to Torrus, and few other structural changes +will accompany the transition. + +=head2 Releases roadmap + +Version 0.1.8 will be the last of RRFW, unless some urgencies arise. + +The first Torrus release will be 1.0.0. + + + +=head2 Multiple XML cofiguration directories + +During XML compilation, the datasource configuration files will be searched in +multiple directories. The list of directories and the search sequence +will be configurable. This will allow not to mix the distribution XML files +and the ones created locally. + +=head2 Separated directories for templates and configuration + +Perl configuration files and HTML templates will also be separated into +different directories, so that user-editable files don't mix with the +ones from distribution. + +=head2 Commandline launcher + +A small shell script will be installed as C</usr/local/bin/torrus>, +and it will pass all arguments to appropriate torrus executables. For example, + + torrus compile --tree=main + +will execute C<compilexml> torrus utility with the argument C<--tree=main>. + + + +=head2 New directory hierarchy + +Filesystem Hierarchy Standard E<lt>http://www.pathname.com/fhs/E<gt> +proposes to put the software add-on packages into C</opt> directory +and user services data, such as database contents or RRD files, in +C</srv> directory. + +However, FreeBSD and some other systems are not FHS-compliant, and require +to install all additional software into C</usr/local> hierarchy. + +We propose that Torrus distribution will support three different directory +layouts, and the system administrator will decide the most suitable one: + +=over 4 + +=item 1 + +Default layout based in C</usr/local>; + +=item 2 + +FHS compliant layout, set by running C<./configure_fhs> instead +of C<./configure>; + +=item 3 + +Custom layout, tunable with standard options and variables in C<./configure>. + +=back + + +=head3 Default layout + +Although many systems like FreeBSD discourage creation of new +package-specific subdirectories in /usr/local, we find it quite a common +practice, and quite convenient for keeping the files together. + + /usr/local/torrus/ Home directory for Torrus distribution files + | + +- conf_defaults/ torrus-config.pl and others + | + +- bin/ Command-line executables + | + +- doc/ POD and TXT documentation files + | + +- examples/ Miscelaneous example files + | + +- perllib/ Perl libraries + | + +- plugins/ Plugins configuration + | + +- scripts/ Scripts + | + +- sup/ Supplementary files, DTDs, MIBs, color schemas, + | Web plain files + | + +- templates/ Renderer output templates + | + +- xmlconfig/ Distrubution XML files + + /usr/local/etc/torrus/ Site configurable files + | + +- conf/ Place for torrus-siteconfig.pl and other siteconfigs + | + +- discovery/ Devdiscover input files + | + +- templates/ User-defined Renderer output templates + | + +- xmlconfig/ User XML configuration files + + /usr/local/man/ Place for man pages. All articles will have the + prefix C<torrus_> + + /var/log/torrus/ Daemon logfiles + + /var/run/torrus/ Daemon PID files + + /var/torrus/cache/ Renderer cache + + /var/torrus/db/ Configuration databases + + /var/torrus/session_data/ Web interface session files + + /srv/torrus/collector_rrd/ Default directory for collector + generated RRD files + + +=head3 FHS compliant layout + + /opt/torrus/ Home directory for Torrus distribution files + | + +- conf_defaults/ torrus-config.pl and others + | + +- bin/ Command-line executables + | + +- doc/ POD and TXT documentation files + | + +- examples/ Miscelaneous example files + | + +- perllib/ Perl libraries + | + +- plugins/ Plugins configuration + | + +- scripts/ Scripts + | + +- sup/ Supplementary files, DTDs, MIBs, color schemas + | + +- templates/ Renderer output templates + | + +- xmlconfig/ Distrubution XML files + + /etc/opt/torrus/ Site configurable files + | + +- conf/ Place for torrus-siteconfig.pl and other siteconfigs + | + +- discovery/ Devdiscover input files + | + +- xmlconfig/ User XML configuration files + + /opt/torrus/share/man/ Place for man pages. All articles will have the + prefix C<torrus_> + + /var/log/torrus/ Daemon logfiles + + /var/run/torrus/ Daemon PID files + + /var/torrus/cache/ Renderer cache + + /var/torrus/session_data/ Web interface session files + + /srv/torrus/db/ Configuration databases + + /srv/torrus/collector_rrd/ Default directory for collector + generated RRD files + + +=head2 New plugins design + +Unlike RRFW, the plugins in Torrus will be installed independently. +This will allow to easily add new plugins to an existing installation. + +The Torrus installer stores all important variable settings in a special +file, F<conf_defaults/instvars>. Then the plugin installer is able +to access the settings without accessing the Torrus distribution +directory. + +There is a helper utility, C<install_plugin>, which applies all +I<configure> variables to the plugin configuration utility. +It follows then the standard installation way: + + ./configure && make && make install + +Thus the OS-dependent package installators may follow the standard +configuration procedure, while those who manually install the software, +will use the helper. + +There are two special directories: F</usr/local/torrus/plugins/torrus-config> +and F</usr/local/torrus/plugins/devdiscover-config>. Plugins are +allowed to add Perl files there. They will be automatically I<require>'d by +F<torrus-config.pl> and F<devdiscover-config.pl>. + + + +=head2 Authors + +Copyright (c) 2004 Stanislav Sinyagin diff --git a/torrus/doc/devdoc/wd.distributed.pod b/torrus/doc/devdoc/wd.distributed.pod new file mode 100644 index 000000000..8dae04915 --- /dev/null +++ b/torrus/doc/devdoc/wd.distributed.pod @@ -0,0 +1,198 @@ +# Copyright (C) 2002 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: wd.distributed.pod,v 1.1 2010-12-27 00:04:36 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 RRFW Working Draft: Distributed collector architecture + +Status: pending implementation. +Date: May 26, 2004. Last revised: June 14, 2004 + +=head2 Introduction + +In large installations, one server has often not enough capacity +to collect the data from all the data sources. In other cases, +because of the network bandwidth or security restrictions it is +preferrable to collect (SNMP) data locally on the site, and transfer +the updates to the central location less frequently. + +=head2 Terminology + +We call I<Hub> servers those which run the user web interfaces and +optionally threshold monitors. These are normally placed in the central +location or NOC datacenter. + +I<Spoke> servers are those running SNMP or other data collectors. +They periodically transfer the data to Hub servers. One Spoke +server may send copies of data to several Hub servers, and one +Hub server may receive data from many Spoke servers. + +In general, the property of being a Hub or a Spoke is local to a pair +of servers and their datasource trees, and it only describes the functions +of data collection and transfer. In complex installations, the same +instance of RRFW may function as a Hub for some remote Spokes, and as a +Spoke for some other Hubs simultaneousely. + +We call I<Association> a set of attributes that describe a single connection +between Hub and Spoke servers. These attributes are: + +=over 4 + +=item * Association ID + +Unique symbolic name across the whole range of interconnected servers. + +=item * Hub server ID, Spoke server ID + +Names of the servers, usually hostnames. + +=item * Transport type + +One of SSH, RSH, HTTP, etc. + +=item * Transport mode + +PUSH or PULL + +=item * Transport parameters + +Parameters needed for this transport connection, like login name, password, +URL, etc. + +=item * Compression type and level + +Optional, gzip or bzip2 or something else, with compression levels from 1 to 9. + +=item * Tree name on Hub server + +Target datasource tree that will receive data from Spokes + +=item * Subtree path on Hub server + +The data updates from this association will be placed in a subtree +under the specified path. + +=item * Tree name on Spoke server + +The tree where a collector runs and stores data into this association. + +=item * Path translation rules + +Datasource paths from Spoke server may be changed to look different +in the tree of Hub server. + +=back + + +=head2 Transport + +The modular architecture design should allow different types of data +transfer. The default transport is Secure Shell version 2 (SSH). Other +possible transports may be RSH, HTTP/HTTPS, rsync. + +Two transport modes should be implemented: PUSH and PULL. +In PUSH mode, Spoke servers initiate the data transfer and push the data to +Hub servers. In PULL mode, Hub servers initiate the data +transfer and ask Spokes for data updates. It should be possible +to mix the transport modes for different Associations on the same +server, but within each Association the mode should be strictly +determined. The choice of transport mode should be based on local security +policies, and server and network performance. + +Optionally the compression method and level can be configured. Although +SSH protocol supports its own compression, more aggressive compression +methods may be used for the sake of better bandwidth usage. + +Transport agents should notify the operator in cases of delivery failures. + +=head2 Operation + +For Spoke servers, distributed data transfer will be implemented as +additional storage type. For Hub servers, this will be a new collector +type. + +Each data transfer is a concatenation of I<messages>. Messages +may be of one of two types: I<CONFIG> and I<DATA>. Spoke server generates +the messages and stores them for the transfer. Messages are delivered +to Hub servers with a certain delay, but they are guaranteed to +arrive in sequential order. For each pair of servers, messages are +consecutively numbered. These numbers are used for failure detection. + +A Spoke server keeps track of its configuration, and after each +configuration change, it sends a CONFIG message. This message contains +information about mapping between Spoke server tokens and datasource paths, +and a limited set of parameters for displaying and monitoring the data. + +After each collector cycle, Spoke server sends DATA messages. +These messages contain the following information: timestamp of the +update, token, and value. The format of the message should be designed +to consume minimum bandwidth. + +Hub server picks up the messages delivered by the transport agents. +Upon receiving a CONFIG message, it sets a preconfigured delay, in order +to collect as many as possible CONFIG messages. Then the data transfer agent +generates a new XML configuration based on the messages, and starts +the compilation of configuration. The DATA messages are queued for the +collector to pick up and and store the values. It must be ensured that +all DATA messages queued for the old configuration are processed before +the compilation starts. + +In case of fatal failure and loss of data, Hub server ignores all DATA +messages until it gets a new CONFIG message. A periodic configuration update +schedule should be defined. If no configuration changes occur within a +certain period of time, Spoke server periodically sends the CONFIG messages +with the same timestamp. + + +=head2 Message format + +Message is a text in email-like format: it starts with a header, followed by +an empty line and the body. Single dot (.) in a line specifies the end of +the message. Blocks within a CONFIG message are separated with semicolon (;), +each block representing a single datasource leaf. + +Example: + + MsgID:100001 + Type:CONFIG + Timestamp:1085528682 + + level2-token:T0005 + level2-path:/Routers/RTR1/Interface_Counters/Ethernet0/InOctets + vertical-label:bps + .... + ; + level2-token:T0006 + level2-path:/Routers/RTR1/Interface_Counters/Ethernet0/OutOctets + vertical-label:bps + . + MsgID:100002 + Type:DATA + Timestamp:1085528690 + + T0005:12345678 + T0006:987654321 + . + + + + +=head1 Author + +Copyright (c) 2004 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> diff --git a/torrus/doc/devdoc/wd.messaging.pod b/torrus/doc/devdoc/wd.messaging.pod new file mode 100644 index 000000000..5d76e114d --- /dev/null +++ b/torrus/doc/devdoc/wd.messaging.pod @@ -0,0 +1,128 @@ +# Copyright (C) 2002 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: wd.messaging.pod,v 1.1 2010-12-27 00:04:36 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 RRFW Working Draft: Messaging subsystem + +Status: pending implementation. +Date: Jun 30 2004. Last revised: + +=head2 Introduction + +Due to the modular and flexible architecture of RRFW, nothing prevents +us from having the possibility of user messages displayed in RRFW pages. +This design document describes the concept of this functionality. + +=head2 Description + +The messaging subsystem will allow the RRFW users to leave comments and +short messages directly at the RRFW pages. Those may be remarks about the +graph contents, troubleshooting journal, etc. + +Each user is uniquely identified by RRFW ACL susbsystem. We introduce several +new attributes and privileges for messaging functionality. Privilege objects +are the tree names. + +Attributes: + +=over 4 + +=item * email + +The user's e-mail where the notifications will be sent + +=item * msgnotify + +When set to true value, e-mail notifications will be sent to this users. + +=back + +Privileges: + +=over 4 + +=item * PostMessages + +allows the user to add messages to the tree objects. + +=item * DisplayMessages + +allows the user to see all messages for the tree + +=item * ReceiveNotifications + +allows the user to receive e-mail notifications. For those notifications +generated by Messages, C<DisplayMessages> must be granted too. + +=item * DeleteMessages + +allows the user to delete messages from the tree objects + +=item * EditMessages + +allows the user to change any message + +=item * EditOwnMessages + +allows the user to change his/her own messages + +=back + +The C<acledit> program will have two additional options that simplify +administration: C<--msguser> will grant all privileges except C<DeleteMessages> +and C<EditMessages>, and C<--msgadmin> will grant all messaging privileges. + +The messaging options database will contain parameters that each user can tune +for himself or herself: + +=over 4 + +=item * Notify when + +a) any new message in all trees; b) (default) new message for +objects that I commented only. + +=item * Notification format + +a) plain text (default); b) HTML; c) RSS 2.0 + +=item * Subject line format + +The format pattern with keywords like C<$TREE>, C<$PATH>, C<$AUTHOR>, +C<$MSGID>, etc. + +Default: + + [rrfw $MSGID] $TREE $AUTHOR: $PATH + +=back + +Each message will have the status of Read/Unread per each user in the system. + +On the tree chooser page in RRFW Web interface, the user will be shown +the unread messages. + +RRS 2.0 feed will be provided for messages export and for integration with +other messaging systems. + + +=head1 Author + +Copyright (c) 2004 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> diff --git a/torrus/doc/devdoc/wd.monitor-escalation.pod b/torrus/doc/devdoc/wd.monitor-escalation.pod new file mode 100644 index 000000000..3dc59796d --- /dev/null +++ b/torrus/doc/devdoc/wd.monitor-escalation.pod @@ -0,0 +1,117 @@ +# Copyright (C) 2002 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: wd.monitor-escalation.pod,v 1.1 2010-12-27 00:04:36 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 RRFW Working Draft: Monitor escalation levels + +Status: pending implementation. +Date: Nov 5 2003. Last revised: Nov 10 2003 + +=head2 Introduction + +The initial idea comes from Francois Mikus in Cricket development team. +His proposal was to raise the alarm only after several true consecutive +monitor conditions. + +The idea has developed into the concept of escalation levels. + + +=head2 Monitor events + +Current implementation supports four types of monitor events: C<set>, +C<repeat>, C<clear>, and C<forget>. New event type will be C<escalate(X)>. +C<X> designates a symbolic name for a certain escalation level. Each level +is associated with the escalation time interval. + +Given C<Te> as the escalation interval, C<Ta> as the monitor condition age, +and C<P> as period, the escalation event will occur simultaneously with +one of C<repeat> events, when the following condition is true: + + Te >= Ta + +New event types C<clear(X)> and C<forget(X)> will occur at the same +time as C<clear> and C<forget> respectively, +for each escalated level. + + +=head2 Monitor parameters + +New parameter will be introduced: C<escalation>. Value will +be a comma-separated list of C<name=interval> parts, where C<name> +designates the escalation level, and C<interval> specifies the escalation +interval in seconds. + +Example: + + <monitor name="rate-limits"> + <param name="escalation value="Medium=1800, High=7200, Critical=14400" /> + ... + </monitor> + +Another example would be Cisco TAC style priorities: P3, P2, P1. + + +=head2 Action parameters + +C<launch-when> parameter will be valid not for C<exec> actions only, but also +for C<tset> actions. New valid values will be C<escalate(X)>, C<clear(X)>, +and C<forget(X)>. + +XML configuration validator will not verify if escalation levels in +action definition match those in datasource configuration. + +New optional action parameter: C<allowed-time>. Contains an RPN expression +which must be true at the time when the action is allowed to execute. +Two new RPN functions may be used here: C<TOD> and C<DOW>. + +C<TOD> returns the current time of day as integer: C<HH*100+MM>. For example, +830 means 8:30 AM, and 1945 means 7:45 PM. + +C<DOW> returns the current day of the week as integer between and including +0 and 6, with 0 corresponding to Sunday, 1 to Monday, and 6 to Saturday. + +In this example, the action is allowed between 8 AM and 6 PM from Monday +to Friday: + + <param name="allowed-time"> + TOD,800,GE, TOD,1800,LE, AND, + DOW,1,GE, AND, + DOW,5,LE, AND + </param> + + +=head2 Implementation + +B<monitor_alarms.db> database format will change: The values will consist +of five colon-separated fields. The first four fields will be as earilier, +and the fifth one will be a comma-separated list of escalation level names +that have already fired. + +The implementation of this feature is preferred after the planned redesign of +the monitor daemon. The new monitor design would support individual +schedule for each datasource leaf, analogous to collector schedules. + +In turn, the monitor daemon redesign is better to do after +the collector daemon redesign. Then it would allow to keep similar design +and architecture where possible. + +=head1 Author + +Copyright (c) 2003 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> diff --git a/torrus/doc/devdoc/wd.uptime-mon.pod b/torrus/doc/devdoc/wd.uptime-mon.pod new file mode 100644 index 000000000..8bc1c423e --- /dev/null +++ b/torrus/doc/devdoc/wd.uptime-mon.pod @@ -0,0 +1,162 @@ +# Copyright (C) 2002 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: wd.uptime-mon.pod,v 1.1 2010-12-27 00:04:36 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 RRFW Working Draft: Service uptime monitoring and reporting + +Status: in pre-design phase. +Date: Sep 26 2003; Last revised: + +=head2 Definitions + +It is often required to monitor the service level in networks. +Service level is normally covered by Service Level Agreement (SLA), +which defines the following parameters: + +=over 4 + +=item * Service definition + +Describes the particular service in terms of functionality and means of +monitoring. Examples are: IP VPN connectivity, WAN uplink, SQL database engine. + +=item * Maintenance window + +Describes the periodic time intervals when service outage is possible +due to some maintenance work. It may be unconditional (outage is always +possible within the window), or conditional (customer confirmation required +for outage within the window). Notification period is normally defined +for maintenance outages. +Example: every 1st Tuesday of the month between 6AM and 8 AM, with 96 hours +notification time. + +=item * Outage types + +Outages may be caused by: 1). system failure; 2). service provider's +infrastructure failure; 3). customer activity. + +=item * Service level objectives + +These are the guarantees that the sevice provider gives to the customer. +Violation of these guarantees is compensated by penalties defined. + +These may include: Maxium maintenance downtime per specified period; +Maximum downtime period due to failures on the service provider side; +Minimum service availability per specified period. + +=back + + +=head2 Event datasource type + +In order to store the service level information, we need a new datasource +type in RRFW: I<event>. It represents an atomic information +about a single event in time, e.g. it canot be devided into more specific +elements or sub-events. Its attributes are as follows: + +=over 4 + +=item * Event group name + +Several events belong to one and only one group. Event group is a unique +entity that describes the service. + +=item * Event name + +Unique name within the event group. Describes the type of the event, such as +C<maintenance>, C<downtime>. Events with the same names cannot overlap in +time. + +=item * Start time + +Timestamp of the event start. + +=item * Duration + +Positive integer that specifies the length of the event in seconds. +Zero duration means that the event has not yet finished. + +=item * Parameters + +Event-specific I<(name, value)> pairs. + +=back + +Events are uniquely identified by I<(Event group, Event name, Start time)> +triple. + + +=head2 Event summary reports + +Renderer should be able to display the events at different summary levels +and in different combinations. Event reports should be specified by +expressions, as follows: + +=over 4 + +=item * Boolean operators + +C<downtime AND NOT maintenance>. + +=item * Time period + +C<(downtime AND NOT maintenance)[-2DAYS,NOW]> + +C<(downtime[-2DAYS,NOW] AND NOT maintenance AND +NOT downtime[200309151200,200309151300])> + +=item * Arithmetic operations + +Sum of durations, substract of durations... + +=back + +=head2 Events generation + +Events may be generated by the following sources: + +=over 4 + +=item * Collector + +SNMP collector may create events on some faulty conditions, like host +unreachable, or on SNMP variables change, like interface status. +Also it's possible to create an ICMP Echo collector type, +which would generate events based on pinging the hosts. + +=item * Monitor + +Obviously, a new monitor action will be to create events. + +=item * Human operator + +First from commandline interface, and later from thr Web interface, +the human operators may create the scheduled events, like maintenance +outages. Security policy should protect certain types of events +from human intervention. + +=back + + + + +=head1 Author + +Copyright (c) 2003 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> diff --git a/torrus/doc/install.pod.in b/torrus/doc/install.pod.in new file mode 100644 index 000000000..3815dadb4 --- /dev/null +++ b/torrus/doc/install.pod.in @@ -0,0 +1,630 @@ +# install.pod - Torrus installation instructions +# Copyright (C) 2002 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: install.pod.in,v 1.1 2010-12-27 00:04:36 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 Torrus Installation Instructions + + + +=head2 Required Software + +=over 4 + +=item * Operating System + +Any UNIX-like operation system where the required components are working. +The author's primary development platform is Cygwin +E<lt>http://www.cygwin.comE<gt>, +and the primary testing environments are Sun Solaris/SPARC and FreeBSD. + +Note to B<VmWare> users: as recommended by Gord Philpott, Linux kernel for +guest machine needs to be compiled with the following feature enabled: +C<Character devices ---E<gt> Enhanced Real Time Clock Support>. +For other guest operating systems (e.g. FreeBSD), in order to let the +Torrus collector and monitor run properly, you need to add the following +lines to your F<torrus-siteconfig.pl>: + + $Torrus::Scheduler::maxSleepTime = 15; + $Torrus::Scheduler::ignoreClockSkew = 1; + +# B<Debian> package is maintained by Jurij Smakov and is available at +# E<lt>http://pkg-torrus.alioth.debian.orgE<gt>. + +=item * Perl + +Perl version C<5.8.1> or higher is required. B<Version C<5.8.0> is not +recommended> because of memory access bugs and unpredictable behaviour. +Perl interpreter should be in PATH environment variable when +running C<./configure>, otherwise use + + ./configure PERL=/path/to/perl + +Torrus also supports Perl multithreading in Device Discovery engine and +in the Collector. Minimum requirements are as follows: Perl version 5.8.8 +or higher, C<threads> module version 1.41 or higher, C<threads::shared> module +version 1.03 or higher. Older versions had bugs that were leading to +severe memory leaks and instability. After installing Perl 5.8.8, +you need to upgrade the C<threads> and C<threads::shared> modules manually +from CPAN. If any of the requirements is not met, the installer will +automatically disable the threads support in Torrus. + +=item * RRDtool + +Round Robin Database Tool is available at: +E<lt>http://ee-staff.ethz.ch/~oetiker/webtools/rrdtool/E<gt>. +Both stable version C<1.0.x> and the development version C<1.1.x> +are supported. + +As of this writing, rrdtool version C<1.1.x> is still in its development +stage, but it is quite ready for using in production environments. +There's a small glitch in legend text alignment, and it will +hopefully be fixed. + +=item * libxml2 + +libxml2 is the XML parser library from Gnome +project E<lt>http://www.gnome.orgE<gt>, +available as a standalone package. +Versions C<2.4.23> and above were tested. + +=item * Berkeley DB version 4.2.52 or later + +There are two distinct packages with slightly conflicting names: +The Berkeley DB from Sleepycat Software E<lt>http://www.sleepycat.comE<gt>, +and C<BerkeleyDB> Perl module available from CPAN. We will always refer +the latter as I<BerkeleyDB Perl module>. + +The Berkeley DB database engine is used for all data storage. +Versions C<4.2.52> and above are recommended. +Older versions of Berkeley DB had problems with database integrity +in concurrent usage. By default, it installs +into F</usr/local/BerkeleyDB.4.2/>. + +Unfortunately, the BerkeleyDB Perl module cannot find the include and +library files in that directory. Thus either configure Berkeley DB +with the option C<--prefix=/usr/local>, or you need to edit +F<config.in> in BerkeleyDB Perl module distribution. + +=item * HTTP Server + +Torrus requires an HTTP server. It is compatible with the following +combinations: + +=over 8 + +=item * Apache 1.3 with mod_perl 1.0 + +=item * Apache 2.x with mod_perl 2.0 + +=item * lighttpd with FastCGI + +=item * Apache with FastCGI + +=back + +FastCGI is supported in Torrus version 1.0.9 or higher. + +B<Note:> Starting from Torrus version 1.0.9, C<libapreq2> is no longer +required. + +See I<Torrus Web Interface Reference> for details on HTTP server configuration. + +=item * Perl Modules + +The Perl modules required are listed below. They are all available at +CPAN E<lt>http://www.cpan.orgE<gt>. +Some of them require other modules to be installed. +You can install all required modules with the following command, +executed from within the distribution directory: + + perl -I `pwd`/setup_tools -MCPAN -e 'install Bundle::Torrus' + +=over 8 + +=item * XML::LibXML + +This is a Perl interface for libxml2, providing DOM standards compliant +interface. It is recommended that you use version C<1.54_3> or higher. + +=item * BerkeleyDB perl module + +Perl interface to the database software. +Version C<0.19> or higher is required. + +=item * Template-Toolkit + +This is a powerful set of tools for text template processing. +Torrus uses it for HTML files output. +See also the project homepage: E<lt>http://www.template-toolkit.orgE<gt> + +=item * Proc::Daemon + +Daemon invocation routines. + +=item * Net::SNMP + +SNMP queries and traps interface. Version C<4.0.3> or higher is required. +I<Note>: Torrus versions prior to 1.0.9 are incompatible with Net::SNMP +version 6.0.0. You may need to downgrate the module to 5.2.0. + +=item * URI::Escape + +Escape and unescape unsafe characters + +=item * Apache (mod_perl version 1.0) + +Mod_perl is a Perl runtime environment integrated into Apache HTTP server. + +=item * Apache::Session + +User session tracking helper + +=item * Date::Parse and Date::Format + +Module for parsing the user input for date and time. + +=item * JSON + +JSON data format support + +=back + + +=item * HTTP Browser requirements + +The HTTP browser must be compatible with I<HTML 4.01 Strict> and I<CSS2> +specifications. The tests were made with the following browsers: +IE 5.5, Opera 6.12B1/Solaris, Opera 7.03/Win2K, Netscape 7.02. + +=back + +=head2 Recommended Software + +=over 4 + +=item * C<XML::XUpdate::LibXML> by Petr Pajas + +This Perl module implements XUpdate specification +E<lt>http://www.xmldb.org/xupdate/E<gt>. See Torrus User Guide for details. + +=item * XSH by Petr Pajas + +Available at E<lt>http://xsh.sourceforge.netE<gt>. +This is a shell wrapper for a set of utilities for XML extraction, browsing, +and editing. + +=item * libxslt from Gnome project + +C<libxslt> is the XSLT stranslation library from Gnome +project E<lt>http://www.gnome.orgE<gt>, available as a standalone package. +It includes a binary executable, C<xsltproc>. See Torrus User Guide for +examples of its usage. + +=back + + + +=head2 Installation Procedure + +Create the group C<torrus> and a user C<torrus>. The user should be a member of +this group. + +Add your Apache daemon user to the group C<torrus>. +Other users that will run any of Torrus processes must be included in +this group. + +For example, in Solaris (you may need to specify the GID and UID numbers +according to your local administration policy): + + groupadd torrus + useradd -c 'Torrus Daemon' -d /usr/local/torrus -g torrus torrus + usermod -G www,torrus www + +Further installation process is mostly as usual: + + ./configure + make + make install + +The default directory layout is described below. Should you need to change it, +there is a number of variables and configuration options that you may use +as C<./configure> arguments. See C<./configure --help> for details. +Alternatively you can utilize the script C<./setup_tools/configure_fhs>, +which is designed to provide an FHS compliant setup. The script is equivalent +to executing + + ./configure \ + --prefix=/opt \ + --mandir=/opt/share/man \ + pkghome=/opt/torrus \ + sitedir=/etc/opt/torrus + +Do not try to change any paths by supplying them as C<make> variables, +this would most probably break the installation. The only C<make> variable +that is supported is C<DESTDIR>. It may be used for preparing the package for +further distribution. For example, the following command would install +all Torrus files as if F</tmp/stage> were the root of the filesystem: + + make DESTDIR=/tmp/stage install + +The presence of prerequisite Perl modules is checked during the execution +of C<./configure>. You can disable this by giving I<--enable-pkgonly> option. + +The installer sets up the site configuration files, but only if +they don't already exist. + +Plugin modules should be installed separately, after the Torrus software is +successfully installed. For each plugin, unpack the plugin distribution archive +to some directory, and execute + + torrus install_plugin <UNPACKED_PLUGIN_DIR> + +A number of directories is set up by default under the path C</var>, +and they must be writable by all Torrus processes, including the +Apache web server. + +You can control these directories' access rights by setting the following +environment variables: I<var_user>, I<var_group>, I<var_mode>, like follows: + + ./configure var_group=wwwrun + +Default values for operating systems other than Cygwin are: I<var_user=torrus>, +I<var_group=torrus>, I<var_mode=775>. Setgid bit is set by default for these +directories. + +If available, you may place these directories on a fast media, for example, +a robust disk array. Changing the C<varprefix> variable would be generally +enough, for example: + + ./configure varprefix=/vol1/torrus_var + + +=head2 Torrus directory layout + + @pkghome@/ + Home directory for Torrus distribution files + + @cfgdefdir@/ + torrus-config.pl and other configuration files + + @pkgbindir@/ + Command-line executables + + @docdir@/ + POD and TXT documentation files + + @exmpdir@/ + Miscelaneous example files + + @perllibdir@/ + Perl libraries + + @pluginsdir@/ + Plugins configuration + + @scriptsdir@/ + Scripts + + @supdir@/ + Supplementary files, DTDs, MIBs, color schemas, web plain files + + @tmpldir@/ + Renderer output templates + + @distxmldir@/ + Distrubution XML files + + @sitedir@/ + Site configurable files + + @siteconfdir@/ + Place for torrus-siteconfig.pl and other siteconfigs + + @siteconfdir@/discovery/ + Devdiscover input files + + @tmpluserdir@/ + User-defined Renderer output templates + + @sitexmldir@/ + User XML configuration files + + @mandir@ + Place for man pages. All articles have the prefix C<torrus_> + + @logdir@/ + Daemon logfiles + + @piddir@ + Daemon PID files + + @cachedir@ + Renderer cache + + @dbhome@ + Berkeley DB home + + @seslockdir@ + @sesstordir@ + Web interface session files + + @defrrddir@ + Recommended directory for RRD files generated by collectors + +B<Note:> RRFW used the path F</var/snmpcollector> as the default path for +storing the RRD files. According to FHS specification, the recommended +path for service data files is recommended to be a subdirectory of F</srv>. +The path F<@defrrddir@> is used as default by C<torrus genddx> +utility, and you can always change it in the command line or in your +DDX files. + +=head2 Configuring Torrus + +The datasources are configured with C<%Torrus::Global::treeConfig> +hash in F<torrus-siteconfig.pl>. + +In this hash, the keys give the tree names. The values for each tree name +are pointers to hashes, with the following keys and values: +I<xmlfiles> points to an array of source XML file names; +I<run> points to a hash with the names of the daemons +that would be automatically launched for the tree; +I<desription> gives a short line describing the tree contents. + +Two additional arrays: C<@Torrus::Global::xmlAlwaysIncludeFirst> and +C<@Torrus::Global::xmlAlwaysIncludeLast> give a list of source XML +files that are included in every tree, in the beginning or in the end of +the XML files list. By default, this array consists of two files: +F<defaults.xml> and F<site-global.xml>. The second one is resided in +the user-configurable directory, and you can use it to override any +default settings. + +Example: + + @Torrus::Global::xmlAlwaysIncludeFirst = + ('defaults.xml', 'site-global.xml'); + + %Torrus::Global::treeConfig = ( + 'tree_A' => { + 'description' => 'The First Tree', + 'xmlfiles' => [qw(a1.xml a2.xml a3.xml)], + 'run' => { 'collector' => 1, 'monitor' => 1 } }, + 'tree_B' => { + 'description' => 'The Second Tree', + 'xmlfiles' => ['b1.xml', 'b2.xml'], + 'run' => {} } + ); + +XML files are read additively within each tree, in the order +as they are listed. The XML compiler searches for the files in several +directories, listed in C<@Torrus::Global::xmlDirs>. By default, this list +conssists of two paths, one for Torrus distribution files, and the other +for user files. + +Files generated by C<devdiscover> usually contain I<include> statements +which add the vendor-specific XML files to the compilation. + +Below follows a short description of some XML files that come with +Torrus distribution. Only F<site-global.xml> is installed in the directory +for user-configurable files, all others are placed in the distribution +directory. + +=over 4 + +=item * defaults.xml + +Default parameters for the root of the datasources tree. +Default view definitions. B<Note:> this file is automatically +overwritten by C<make install>. + +=item * site-global.xml + +Parameters that you want to change or define for your site. +This file will be compiled for every tree after F<defaults.xml>, +and this is the place to override the defaults. The file that is supplied +with the Torrus distribution has some useful parameters that you may simply +uncomment. +B<Note:> this file is never overwritten by C<make install>. + +=item * snmp-defs.xml + +SNMP collector defaults. The file defines several templates +used for collecting SNMP data. +Do not change this file. +You may redefine the needed parameters in your site-specific files +and templates. + +=item * vendor/E<lt>vendorE<gt>.E<lt>productE<gt>[.E<lt>subsystemE<gt>].xml + +SNMP collector definitions and templates for various hardware vendors and +products. C<devdiscover> includes some of these files automatically in the +configuration. + +=item * generic/*.xml + +SNMP collector definitions and templates for vendor-independent MIBs. Most +files are named after corresponding RFC numbers. + +=back + +In addition, the distribution package contains several example files. + +For more details about XML configuration, see I<Torrus User Guide> +and I<Torrus XML Configuration Guide>. + +=head2 Site configuration options + +In addition to I<%Torrus::Global::treeConfig>, you may wish to set +some other parameters in your site configuration file +(F<torrus-siteconfig.pl>). + +See F<torrus-config.pl> for the complete list +of varaibes that you may override in your site config. Among them, +most interesting are: + +=over 4 + +=item * C<$Torrus::Renderer::companyName> + +The text that you specify here will appear in the top left corner +of all HTML pages. + +=item * C<$Torrus::Renderer::companyURL> + +The company name text will be clickable with the URL specified in +this variable. + +=back + + +=head2 Apache HTTP server configuration + +Torrus web interface is designed to run under mod_perl environment +(E<lt>http://perl.apache.orgE<gt>). + +See the I<Torrus Web Interface Reference> document for detailed instructions on +Apache configuration. + +In short, typical Apache configuration for mod_perl version 1.0 would look +like follows: + + Alias /torrus/plain "@webplaindir@" + PerlRequire "@cfgdefdir@/webmux.pl" + <Location /torrus> + SetHandler perl-script + PerlHandler Torrus::ApacheHandler + </Location> + <Location /torrus/plain/> + SetHandler default-handler + Options None + </Location> + +=head2 Access Control Lists + +By default, Torrus web interface requires user authentication. +You can disable this by changing C<$Torrus::CGI::authorizeUsers> +to zero in your F<torrus-siteconfig.pl>. + +ACLs are controlled by C<acledit> utility. See I<Torrus Manual pages> +for detailed description. Example: + + torrus acledit --addgroup=staff --permit=DisplayTree --for='*' + torrus acledit --addgroup=staff --permit=GlobalSearch --for='*' + torrus acledit --adduser=jsmith --password=mysecretpassword \ + --cn="John Smith" --addtogroup=staff + torrus acledit --addgroup=admin \ + --permit=DisplayTree --permit=DisplayAdmInfo --for='*' + +=head2 Cron Job + +In order to clean old HTTP session data, it is recommended to run +F<cleanup> script in a cron job, once per day: + + #min hour mday month wday who command + 5 3 * * * root @pkgbindir@/cleanup + + +=head2 Startup script + +The Torrus distriubution provides a startup script which you can install in +the init scripts directory (/etc/init.d on most Unixes or /usr/local/etc/rc.d/ +on FreeBSD). The script C<torrus> is created during the installation +process in the subdirectory <init.d> of the distribution directory. + +The init script reads some parameters from F<@cfgdefdir@/initscript.conf>, +and F<@siteconfdir@/initscript.siteconf> if the latter exists. +By default, it makes the monitor daemons sleep for 20 minutes when +they are launched simultaneously with collector daemons. + + +=head2 Upgrade Procedure + +Follow these instructions when upgrading from previous Torrus release. + +In the previous distribution directory, look up the F<config.log> file. +It contains the configure options that you used in previous installation. + +Unpack the new release distribution. + +Run C<./configure> with the same options you used before. + +Stop the collector and monitor processes +(usually by C</etc/init.d/torrus stop>). + +Stop Apache process. + +Run C<make install>. + +Start the collector and monitor processes. + +Start Apache process. + +Also it is recommended to re-compile your XML configuration. +If you prefer not to do this, it's recommended that you clear the +Web interface cache both in your browser and in Torrus: + + torrus clearcache + + +=head2 Planning the disk space + +In a typical Torrus setup, there are two disk space consuming entities: +the RRDtool data storage and the Berkeley DB database. + +RRDtool data files (or RRD's) are used to store the values that are gathered +by the collector daemons. These are the most intensively updated files, +so the disk speed is important here. If possible, it is better to spread +the RRD files across several physical disks. + +Berkeley DB database is used to keep all the configuratiuon data +for your datasource trees, and it also keeps some live status information. +It's intensively updated during XML compilation only. +During normal Torrus working cycle, there are only few updates, not +very critical in time. The database is read quite intensively during +collector initialization, but usually it's the CPU speed that causes +more delay. + +For a typical Torrus installation with standard RRD creation parameters, +the rough estimation is as follows: the Berkeley DB database occupies +from 10 to 13 KB per collector datasource, and the RRD storage takes +approximately 80 to 85 KB per datasource. + +For a medium-sized system, few hundred megabytes for the Berkeley DB database +and several gigabytes for RRD storage would be sufficient. Larger systems +require a thorough design and staging work. See I<Torrus Scalability Guide> +for more details. + +=head2 Network performance tuning + +In large installations, the SNMP collector experiences quite intensive +input traffic bursts. Thus the UDP socket receive buffers should +be adapted to sustain the load. By default, Torrus sets the UDP receiving +buffer size, SO_RCVBUF, to 131071 bytes. This should fit most of +installations. However, it's useful to check the network statistics +if there are any UDP buffer overflows. On most systems, the commands +C<netstat -s -p udp> or C<netstat -s> should show you these counters. +The maximum buffer size is usually limited by a system kernel variable, +and can be increased if needed. See C<$Torrus::Collector::SNMP::RxBuffer> +and its comments in F<torrus-config.pl> for more details. + + +=head1 Author + +Copyright (c) 2002-2007 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> diff --git a/torrus/doc/manpages/Makefile.am b/torrus/doc/manpages/Makefile.am new file mode 100644 index 000000000..1f53b8764 --- /dev/null +++ b/torrus/doc/manpages/Makefile.am @@ -0,0 +1,134 @@ + +# Copyright (C) 2002 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: Makefile.am,v 1.1 2010-12-27 00:04:38 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# + +SUBST = @abs_top_builddir@/setup_tools/substvars.sh + +EXTRA_DIST = $(SRCPOD) +CLEANFILES = $(PODMAN) $(POD_FILES) + +SRCPOD = \ + torrus.pod.in \ + torrus_acledit.pod.in \ + torrus_action_notify.pod.in \ + torrus_action_printemail.pod.in \ + torrus_action_snmptrap.pod.in \ + torrus_buildsearchdb.pod.in \ + torrus_cleanup.pod.in \ + torrus_clearcache.pod.in \ + torrus_collector.pod.in \ + torrus_compilexml.pod.in \ + torrus_configinfo.pod.in \ + torrus_configsnapshot.pod.in \ + torrus_devdiscover.pod.in \ + torrus_flushmonitors.pod.in \ + torrus_genddx.pod.in \ + torrus_genlist.pod.in \ + torrus_genreport.pod.in \ + torrus_install_plugin.pod.in \ + torrus_monitor.pod.in \ + torrus_nodeid.pod.in \ + torrus_rrddir2xml.pod.in \ + torrus_schedulerinfo.pod.in \ + torrus_snmpfailures.pod.in \ + torrus_srvderive.pod.in \ + torrus_ttproclist.pod.in + +POD_FILES = \ + torrus.pod \ + torrus_acledit.pod \ + torrus_action_notify.pod \ + torrus_action_printemail.pod \ + torrus_action_snmptrap.pod \ + torrus_buildsearchdb.pod \ + torrus_cleanup.pod \ + torrus_clearcache.pod \ + torrus_collector.pod \ + torrus_compilexml.pod \ + torrus_configinfo.pod \ + torrus_configsnapshot.pod \ + torrus_devdiscover.pod \ + torrus_flushmonitors.pod \ + torrus_genddx.pod \ + torrus_genlist.pod \ + torrus_genreport.pod \ + torrus_install_plugin.pod \ + torrus_monitor.pod \ + torrus_nodeid.pod \ + torrus_rrddir2xml.pod \ + torrus_schedulerinfo.pod \ + torrus_snmpfailures.pod \ + torrus_srvderive.pod \ + torrus_ttproclist.pod + +PODMAN = \ + torrus.@mansec_usercmd@ \ + torrus_acledit.@mansec_usercmd@ \ + torrus_action_notify.@mansec_misc@ \ + torrus_action_printemail.@mansec_misc@ \ + torrus_action_snmptrap.@mansec_misc@ \ + torrus_buildsearchdb.@mansec_usercmd@ \ + torrus_cleanup.@mansec_usercmd@ \ + torrus_clearcache.@mansec_usercmd@ \ + torrus_collector.@mansec_usercmd@ \ + torrus_compilexml.@mansec_usercmd@ \ + torrus_configinfo.@mansec_usercmd@ \ + torrus_configsnapshot.@mansec_usercmd@ \ + torrus_devdiscover.@mansec_usercmd@ \ + torrus_flushmonitors.@mansec_usercmd@ \ + torrus_genddx.@mansec_usercmd@ \ + torrus_genlist.@mansec_usercmd@ \ + torrus_genreport.@mansec_usercmd@ \ + torrus_install_plugin.@mansec_misc@ \ + torrus_monitor.@mansec_usercmd@ \ + torrus_nodeid.@mansec_usercmd@ \ + torrus_rrddir2xml.@mansec_usercmd@ \ + torrus_schedulerinfo.@mansec_usercmd@ \ + torrus_snmpfailures.@mansec_usercmd@ \ + torrus_srvderive.@mansec_usercmd@ \ + torrus_ttproclist.@mansec_usercmd@ + + + +if POD2MAN_PRESENT +install-data-local: $(POD_FILES) + for f in $(PODMAN); do \ + base=`echo $$f | sed -e 's/\\.[0-9a-zA-Z]*$$//'`; \ + ext=`echo $$f | sed -e 's/^.*\\.//'`; \ + instdir=$(DESTDIR)$(mandir)/man$$ext; \ + echo BASE=$$base EXT=$$ext INSTDIR=$$instdir; \ + $(POD2MAN) --section=$$ext \ + --release="$(PACKAGE_STRING)" --center=torrus \ + $$base.pod > $$f || exit 1; \ + test -d $$instdir || $(mkinstalldirs) $$instdir || exit 1; \ + $(INSTALL_DATA) $$f $$instdir; \ + rm $$f; \ + done +endif + + +SUFFIXES = .pod.in .pod + +.PRECIOUS: $(POD_FILES) + +.pod.in.pod: + $(SUBST) $< > $@ + +pods: $(POD_FILES) diff --git a/torrus/doc/manpages/Makefile.in b/torrus/doc/manpages/Makefile.in new file mode 100644 index 000000000..d8cdedfc4 --- /dev/null +++ b/torrus/doc/manpages/Makefile.in @@ -0,0 +1,445 @@ +# Makefile.in generated by automake 1.9.6 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, +# 2003, 2004, 2005 Free Software Foundation, Inc. +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ + +# Copyright (C) 2002 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: Makefile.in,v 1.1 2010-12-27 00:04:38 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +srcdir = @srcdir@ +top_srcdir = @top_srcdir@ +VPATH = @srcdir@ +pkgdatadir = $(datadir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +top_builddir = ../.. +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +INSTALL = @INSTALL@ +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +build_triplet = @build@ +host_triplet = @host@ +subdir = doc/manpages +DIST_COMMON = $(srcdir)/Makefile.am $(srcdir)/Makefile.in +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/configure.ac +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +mkinstalldirs = $(install_sh) -d +CONFIG_CLEAN_FILES = +SOURCES = +DIST_SOURCES = +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +ACLOCAL = @ACLOCAL@ +AMTAR = @AMTAR@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +CYGPATH_W = @CYGPATH_W@ +DEFS = @DEFS@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +FIND = @FIND@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +KILL = @KILL@ +LIBOBJS = @LIBOBJS@ +LIBS = @LIBS@ +LTLIBOBJS = @LTLIBOBJS@ +MAKEINFO = @MAKEINFO@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +PERL = @PERL@ +PERLINC = @PERLINC@ +POD2MAN = @POD2MAN@ +POD2MAN_PRESENT_FALSE = @POD2MAN_PRESENT_FALSE@ +POD2MAN_PRESENT_TRUE = @POD2MAN_PRESENT_TRUE@ +POD2TEXT = @POD2TEXT@ +POD2TEXT_PRESENT_FALSE = @POD2TEXT_PRESENT_FALSE@ +POD2TEXT_PRESENT_TRUE = @POD2TEXT_PRESENT_TRUE@ +RM = @RM@ +SED = @SED@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +SLEEP = @SLEEP@ +STRIP = @STRIP@ +SU = @SU@ +VERSION = @VERSION@ +ac_ct_STRIP = @ac_ct_STRIP@ +am__leading_dot = @am__leading_dot@ +am__tar = @am__tar@ +am__untar = @am__untar@ +bindir = @bindir@ +build = @build@ +build_alias = @build_alias@ +build_cpu = @build_cpu@ +build_os = @build_os@ +build_vendor = @build_vendor@ +cachedir = @cachedir@ +cfgdefdir = @cfgdefdir@ +datadir = @datadir@ +dbhome = @dbhome@ +defrrddir = @defrrddir@ +distxmldir = @distxmldir@ +enable_pkgonly = @enable_pkgonly@ +enable_varperm = @enable_varperm@ +exec_prefix = @exec_prefix@ +exmpdir = @exmpdir@ +host = @host@ +host_alias = @host_alias@ +host_cpu = @host_cpu@ +host_os = @host_os@ +host_vendor = @host_vendor@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localstatedir = @localstatedir@ +logdir = @logdir@ +mandir = @mandir@ +mansec_misc = @mansec_misc@ +mansec_usercmd = @mansec_usercmd@ +mkdir_p = @mkdir_p@ +oldincludedir = @oldincludedir@ +perlithreads = @perlithreads@ +perllibdir = @perllibdir@ +perllibdirs = @perllibdirs@ +piddir = @piddir@ +pkgbindir = @pkgbindir@ +pkgdocdir = @pkgdocdir@ +pkghome = @pkghome@ +plugdevdisccfgdir = @plugdevdisccfgdir@ +pluginsdir = @pluginsdir@ +plugtorruscfgdir = @plugtorruscfgdir@ +plugwrapperdir = @plugwrapperdir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +reportsdir = @reportsdir@ +sbindir = @sbindir@ +scriptsdir = @scriptsdir@ +seslockdir = @seslockdir@ +sesstordir = @sesstordir@ +sharedstatedir = @sharedstatedir@ +siteconfdir = @siteconfdir@ +sitedir = @sitedir@ +sitexmldir = @sitexmldir@ +supdir = @supdir@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ +tmpldir = @tmpldir@ +tmpluserdir = @tmpluserdir@ +torrus_user = @torrus_user@ +var_group = @var_group@ +var_mode = @var_mode@ +var_user = @var_user@ +varprefix = @varprefix@ +webplaindir = @webplaindir@ +webscriptsdir = @webscriptsdir@ +wrapperdir = @wrapperdir@ +SUBST = @abs_top_builddir@/setup_tools/substvars.sh +EXTRA_DIST = $(SRCPOD) +CLEANFILES = $(PODMAN) $(POD_FILES) +SRCPOD = \ + torrus.pod.in \ + torrus_acledit.pod.in \ + torrus_action_notify.pod.in \ + torrus_action_printemail.pod.in \ + torrus_action_snmptrap.pod.in \ + torrus_buildsearchdb.pod.in \ + torrus_cleanup.pod.in \ + torrus_clearcache.pod.in \ + torrus_collector.pod.in \ + torrus_compilexml.pod.in \ + torrus_configinfo.pod.in \ + torrus_configsnapshot.pod.in \ + torrus_devdiscover.pod.in \ + torrus_flushmonitors.pod.in \ + torrus_genddx.pod.in \ + torrus_genlist.pod.in \ + torrus_genreport.pod.in \ + torrus_install_plugin.pod.in \ + torrus_monitor.pod.in \ + torrus_nodeid.pod.in \ + torrus_rrddir2xml.pod.in \ + torrus_schedulerinfo.pod.in \ + torrus_snmpfailures.pod.in \ + torrus_srvderive.pod.in \ + torrus_ttproclist.pod.in + +POD_FILES = \ + torrus.pod \ + torrus_acledit.pod \ + torrus_action_notify.pod \ + torrus_action_printemail.pod \ + torrus_action_snmptrap.pod \ + torrus_buildsearchdb.pod \ + torrus_cleanup.pod \ + torrus_clearcache.pod \ + torrus_collector.pod \ + torrus_compilexml.pod \ + torrus_configinfo.pod \ + torrus_configsnapshot.pod \ + torrus_devdiscover.pod \ + torrus_flushmonitors.pod \ + torrus_genddx.pod \ + torrus_genlist.pod \ + torrus_genreport.pod \ + torrus_install_plugin.pod \ + torrus_monitor.pod \ + torrus_nodeid.pod \ + torrus_rrddir2xml.pod \ + torrus_schedulerinfo.pod \ + torrus_snmpfailures.pod \ + torrus_srvderive.pod \ + torrus_ttproclist.pod + +PODMAN = \ + torrus.@mansec_usercmd@ \ + torrus_acledit.@mansec_usercmd@ \ + torrus_action_notify.@mansec_misc@ \ + torrus_action_printemail.@mansec_misc@ \ + torrus_action_snmptrap.@mansec_misc@ \ + torrus_buildsearchdb.@mansec_usercmd@ \ + torrus_cleanup.@mansec_usercmd@ \ + torrus_clearcache.@mansec_usercmd@ \ + torrus_collector.@mansec_usercmd@ \ + torrus_compilexml.@mansec_usercmd@ \ + torrus_configinfo.@mansec_usercmd@ \ + torrus_configsnapshot.@mansec_usercmd@ \ + torrus_devdiscover.@mansec_usercmd@ \ + torrus_flushmonitors.@mansec_usercmd@ \ + torrus_genddx.@mansec_usercmd@ \ + torrus_genlist.@mansec_usercmd@ \ + torrus_genreport.@mansec_usercmd@ \ + torrus_install_plugin.@mansec_misc@ \ + torrus_monitor.@mansec_usercmd@ \ + torrus_nodeid.@mansec_usercmd@ \ + torrus_rrddir2xml.@mansec_usercmd@ \ + torrus_schedulerinfo.@mansec_usercmd@ \ + torrus_snmpfailures.@mansec_usercmd@ \ + torrus_srvderive.@mansec_usercmd@ \ + torrus_ttproclist.@mansec_usercmd@ + +SUFFIXES = .pod.in .pod +all: all-am + +.SUFFIXES: +.SUFFIXES: .pod.in .pod +$(srcdir)/Makefile.in: $(srcdir)/Makefile.am $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh \ + && exit 0; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu doc/manpages/Makefile'; \ + cd $(top_srcdir) && \ + $(AUTOMAKE) --gnu doc/manpages/Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ + esac; + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +uninstall-info-am: +tags: TAGS +TAGS: + +ctags: CTAGS +CTAGS: + + +distdir: $(DISTFILES) + @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's|.|.|g'`; \ + list='$(DISTFILES)'; for file in $$list; do \ + case $$file in \ + $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \ + $(top_srcdir)/*) file=`echo "$$file" | sed "s|^$$topsrcdirstrip/|$(top_builddir)/|"`;; \ + esac; \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + dir=`echo "$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test "$$dir" != "$$file" && test "$$dir" != "."; then \ + dir="/$$dir"; \ + $(mkdir_p) "$(distdir)$$dir"; \ + else \ + dir=''; \ + fi; \ + if test -d $$d/$$file; then \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -pR $(srcdir)/$$file $(distdir)$$dir || exit 1; \ + fi; \ + cp -pR $$d/$$file $(distdir)$$dir || exit 1; \ + else \ + test -f $(distdir)/$$file \ + || cp -p $$d/$$file $(distdir)/$$file \ + || exit 1; \ + fi; \ + done +check-am: all-am +check: check-am +all-am: Makefile +installdirs: +install: install-am +install-exec: install-exec-am +install-data: install-data-am +uninstall: uninstall-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-am +install-strip: + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + `test -z '$(STRIP)' || \ + echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install +mostlyclean-generic: + +clean-generic: + -test -z "$(CLEANFILES)" || rm -f $(CLEANFILES) + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." +@POD2MAN_PRESENT_FALSE@install-data-local: +clean: clean-am + +clean-am: clean-generic mostlyclean-am + +distclean: distclean-am + -rm -f Makefile +distclean-am: clean-am distclean-generic + +dvi: dvi-am + +dvi-am: + +html: html-am + +info: info-am + +info-am: + +install-data-am: install-data-local + +install-exec-am: + +install-info: install-info-am + +install-man: + +installcheck-am: + +maintainer-clean: maintainer-clean-am + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-generic + +mostlyclean: mostlyclean-am + +mostlyclean-am: mostlyclean-generic + +pdf: pdf-am + +pdf-am: + +ps: ps-am + +ps-am: + +uninstall-am: uninstall-info-am + +.PHONY: all all-am check check-am clean clean-generic distclean \ + distclean-generic distdir dvi dvi-am html html-am info info-am \ + install install-am install-data install-data-am \ + install-data-local install-exec install-exec-am install-info \ + install-info-am install-man install-strip installcheck \ + installcheck-am installdirs maintainer-clean \ + maintainer-clean-generic mostlyclean mostlyclean-generic pdf \ + pdf-am ps ps-am uninstall uninstall-am uninstall-info-am + + +@POD2MAN_PRESENT_TRUE@install-data-local: $(POD_FILES) +@POD2MAN_PRESENT_TRUE@ for f in $(PODMAN); do \ +@POD2MAN_PRESENT_TRUE@ base=`echo $$f | sed -e 's/\\.[0-9a-zA-Z]*$$//'`; \ +@POD2MAN_PRESENT_TRUE@ ext=`echo $$f | sed -e 's/^.*\\.//'`; \ +@POD2MAN_PRESENT_TRUE@ instdir=$(DESTDIR)$(mandir)/man$$ext; \ +@POD2MAN_PRESENT_TRUE@ echo BASE=$$base EXT=$$ext INSTDIR=$$instdir; \ +@POD2MAN_PRESENT_TRUE@ $(POD2MAN) --section=$$ext \ +@POD2MAN_PRESENT_TRUE@ --release="$(PACKAGE_STRING)" --center=torrus \ +@POD2MAN_PRESENT_TRUE@ $$base.pod > $$f || exit 1; \ +@POD2MAN_PRESENT_TRUE@ test -d $$instdir || $(mkinstalldirs) $$instdir || exit 1; \ +@POD2MAN_PRESENT_TRUE@ $(INSTALL_DATA) $$f $$instdir; \ +@POD2MAN_PRESENT_TRUE@ rm $$f; \ +@POD2MAN_PRESENT_TRUE@ done + +.PRECIOUS: $(POD_FILES) + +.pod.in.pod: + $(SUBST) $< > $@ + +pods: $(POD_FILES) +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/torrus/doc/manpages/torrus.pod.in b/torrus/doc/manpages/torrus.pod.in new file mode 100644 index 000000000..674b5ae21 --- /dev/null +++ b/torrus/doc/manpages/torrus.pod.in @@ -0,0 +1,98 @@ +# Copyright (C) 2004 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: torrus.pod.in,v 1.1 2010-12-27 00:04:37 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 NAME + +torrus - Commandline wrapper for Torrus utilities + +=head1 SYNOPSIS + +B<torrus> I<command> [I<options...>] + +=head1 DESCRIPTION + +All Torrus utilities use this common command-line wrapper, which simply +passes all arguments to the appropriate utility. + +Accepted commands: + +=over 4 + +=item B<acledit> + +=item B<cleanup> + +=item B<clearcache> + +=item B<collector> + +=item B<compilexml> + +=item B<configinfo> + +=item B<configsnapshot> + +=item B<devdiscover> + +=item B<genddx> + +=item B<genlist> + +=item B<install_plugin> + +=item B<monitor> + +=item B<rrddir2xml> + +=item B<schedulerinfo> + +=item B<srvderive> + +=back + +=head1 OPTIONS + +Refer to approproate manpages for options for each Torrus command. + +=head1 SEE ALSO + +L<torrus_acledit(@mansec_usercmd@)>, +L<torrus_action_printemail(@mansec_misc@)>, +L<torrus_action_snmptrap(@mansec_misc@)>, +L<torrus_clearcache(@mansec_usercmd@)>, +L<torrus_collector(@mansec_usercmd@)>, +L<torrus_compilexml(@mansec_usercmd@)>, +L<torrus_configinfo(@mansec_usercmd@)>, +L<torrus_configsnapshot(@mansec_usercmd@)>, +L<torrus_devdiscover(@mansec_usercmd@)>, +L<torrus_genddx(@mansec_usercmd@)>, +L<torrus_monitor(@mansec_usercmd@)>, +L<torrus_rrddir2xml(@mansec_usercmd@)>, +L<torrus_schedulerinfo(@mansec_usercmd@)> +L<torrus_srvderive(@mansec_usercmd@)> + +=head1 NOTES + +See more documentation at Torrus home page: http://torrus.org + +=head1 AUTHOR + +Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> diff --git a/torrus/doc/manpages/torrus_acledit.pod.in b/torrus/doc/manpages/torrus_acledit.pod.in new file mode 100644 index 000000000..eab10ac0a --- /dev/null +++ b/torrus/doc/manpages/torrus_acledit.pod.in @@ -0,0 +1,212 @@ +# Copyright (C) 2004 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: torrus_acledit.pod.in,v 1.1 2010-12-27 00:04:39 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 NAME + +acledit - Manage Torrus access control lists (ACLs). + +=head1 SYNOPSIS + +B<torrus acledit> [I<options...>] + +=head1 DESCRIPTION + +This command manages the Torrus access control lists. Each user is +identified by user ID, and has a set of attributes. Currently +supported attributes are C<cn> (common name) and C<userPasswordMD5> +(MD5 digest of the user's password). + +Each user belongs to one or several groups. Each group has its own +set of privileges. A privilege is identified by privilege name and +object name. Currently only one privilege name is supported: +C<DisplayTree>, and the object name is the name of the tree that +this group is allowed to browse. + +User authorization in the web interface is controlled by the +C<$Torrus::CGI::authorizeUsers> variable in F<torrus-siteconfig.pl>. + +=head1 GROUP MANAGEMENT OPTIONS + +=over 4 + +=item B<--addgroup>=I<GROUP> + +Creates a new group with the given name. + +=item B<--delgroup>=I<GROUP> + +Deletes the group with the given name. + +=item B<--modgroup>=I<GROUP> + +Modifies the given group. + +=item B<--permit>=I<PRIVILEGE> + +Grants privilege to group(s). Currently supported privileges are: +C<DisplayTree> for displaying a datasource tree, and C<DisplayAdmInfo> +for displaying the administrative information (all significant +parameters for a given datasource leaf). + +=item B<--deny>=I<PRIVILEGE> + +Revokes group(s) privilege. + +=item B<--for>=I<OBJECT> + +Object for which privileges are granted or revoked. Currently it must be +the name of the tree for which the C<DisplayTree> and C<DisplayAdmInfo> +privilegs are granted or revoked. The asterisk (*) instead of the object +name assigns the privilege for all objects. + +=back + + +=head1 USER MANAGEMENT OPTIONS + +=over 4 + +=item B<--adduser>=I<UID> + +Creates a new user with the given user ID. + +=item B<--addhost>=I<HOST> + +Creates a new user for host-based authentication. I<HOST> should be an +IPv4 or IPv6 address of the HTTP client. The new username is the address +with all non-alphanumeric characters replaced with underscores. +Host password is changed by <--hostpassword> option. + +=item B<--deluser>=I<UID> + +Deletes user with the given user ID. + +=item B<--moduser>=I<UID> + +Modifies the user attributes for the given user ID. + +=item B<--addtogroup>=I<GROUP> + +Adds user to the given group. + +=item B<--delfromgroup>=I<GROUP> + +Deletes user from the given group. + +=item B<--password>=I<PASSWORD> + +Sets user's password. + +=item B<--hostpassword>=I<PASSWORD> + +Sets the password for host-based authentication. The HTTP client should +add C<hostauth> parameter with the password as a value. + +=item B<--cn>=I<NAME> + +Sets user's common name. + +=item B<--showuser>=I<UID> + +Displays information for a given user. + +=back + + +=head1 GENERAL OPTIONS + +=over 4 + +=item B<--export>=I<FILE> + +Exports ACL configuration to a given file. + +=item B<--template>=I<FILE> + +Uses the given template file when exporting. Default value is F<aclexport.xml>. + +=item B<--import>=I<FILE> + +Imports ACL configuration from the given file. + +=item B<--clear> + +Deletes all user and privileges configuration. + +=item B<--list> + +Lists all users and groups they belong to. + +=item B<--debug> + +Sets the log level to debug. + +=item B<--verbose> + +Sets the log level to info. + +=item B<--help> + +Displays a help message. + +=back + + +=head1 EXAMPLES + + torrus acledit --addgroup=staff --permit=DisplayTree \ + --for=main --for=thecustomer + torrus acledit --adduser=jsmith --password=mysecretpassword \ + --cn="John Smith" --addtogroup=staff + torrus acledit --addgroup=admin --permit=DisplayTree --for='*' + +This example creates a group I<staff> and gives all its members the permission +to browse the datasource trees I<main> and I<thecustomer>. The next command +creates a user I<jsmith> and addts it to this group. The user name will +be displayed as I<John Smith>, and it will be let in with the given +password. The third command creates a group I<admin> which is allowed +o browse all existing trees. + +=head1 FILES + +=over 4 + +=item F<@siteconfdir@/torrus-siteconfig.pl> + +Torrus site configuration script. + +=item F<@tmpldir@/aclexport.xml> + +Default template for the exports of ACL configuration. + +=back + +=head1 SEE ALSO + +L<torrus(@mansec_usercmd@)> + +=head1 NOTES + +See more documentation at Torrus home page: http://torrus.org + +=head1 AUTHOR + +Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> diff --git a/torrus/doc/manpages/torrus_action_notify.pod.in b/torrus/doc/manpages/torrus_action_notify.pod.in new file mode 100644 index 000000000..386c3d923 --- /dev/null +++ b/torrus/doc/manpages/torrus_action_notify.pod.in @@ -0,0 +1,100 @@ +# Copyright (C) 2006 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: torrus_action_notify.pod.in,v 1.1 2010-12-27 00:04:39 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 NAME + +action_notify - Generic notification handler for Torrus monitor + +=head1 SYNOPSIS + + <action name="notify"> + <param name="action-type" value="exec" /> + <param name="command"> + $TORRUS_BIN/action_notify + </param> + <param name="launch-when" value="set" /> + </action> + +=head1 DESCRIPTION + +This program is designed for usage from a monitor action only. It takes +the arguments from environment variables, as described in action-type +C<exec> in B<Torrus XML Configuration Guide>. + +The handler reads its configuration from <notify-siteconfig.pl>, a small +Perl file which defines the notification paths for various conditions. + +Example: + + %Torrus::Notify::programs = + ( + 'mailto' => '$TORRUS_BIN/action_printemail | /usr/bin/mail $ARG1', + 'page' => '/usr/bin/echo $TORRUS_NODEPATH:$TORRUS_MONITOR ' . + '>> /tmp/monitor.$ARG1.log' + ); + + %Torrus::Notify::policies = + ( + 'CUST_A' => { + 'match' => sub { $ENV{'TORRUS_P_notify_policy'} eq 'A' }, + 'severity' => { + '3' => [ 'mailto:aaa@domain.com', + 'mailto:bbb@domain.com' ], + '5' => [ 'page:1234', 'mailto:boss@domain.com' ] } } ); + + +In this example, we define two message handlers: e-mail sender and +a dummy replacement for a pager program. Then we define the notification +policies. For the customer I<A>, we define the policy so that +the parameter C<notify-policy> should match the name C<A>. The parameter +is defined in the datasource tree and marks only those leaves +that belong to this customer. +Then, depending on the monitor severity, different notification +paths are defined. For severity values higher or equal 3, aaa@domain.com and +bbb@domain.com will receive the email notifications, and for severity +higher than or equal 5 all recipients will receive the notification. + +The C<match> argument is a Perl subroutine, and can depend on various +parameters, such as time of day or day of the week, the tree name, and so on. + + +=head1 FILES + +=over 4 + +=item F<@siteconfdir@/notify-siteconfig.pl> + +Notification policies configuration + + +=back + +=head1 SEE ALSO + +L<torrus(@mansec_usercmd@)> + +=head1 NOTES + +See more documentation at Torrus home page: http://torrus.org + +=head1 AUTHOR + +Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> diff --git a/torrus/doc/manpages/torrus_action_printemail.pod.in b/torrus/doc/manpages/torrus_action_printemail.pod.in new file mode 100644 index 000000000..e63b94e4b --- /dev/null +++ b/torrus/doc/manpages/torrus_action_printemail.pod.in @@ -0,0 +1,101 @@ +# Copyright (C) 2004 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: torrus_action_printemail.pod.in,v 1.1 2010-12-27 00:04:38 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 NAME + +action_printemail - A script for sending email from monitor action. + +=head1 SYNOPSIS + + <action name="report-email"> + <param name="action-type" value="exec" /> + <param name="command"> + $TORRUS_BIN/action_printemail | mail alarms@example.com + </param> + <param name="launch-when" value="set, clear" /> + </action> + +=head1 DESCRIPTION + +This program is designed for usage from a monitor action only. It takes +the arguments from environment variables, as described in action-type +C<exec> in B<Torrus XML Configuration Guide>. In addition, some values +may be supplied via command-line arguments (see section OPTIONS below). + +Site-specific variables must be specified in the file F<email-siteconfig.pl>. +Default values are installed by the first run of C<make install>. Subsequent +runs of C<make install> do not override this file. + +=head1 OPTIONS + +=over 4 + +=item B<--url>=I<GRAPHER-URL> + +Sets the URL of the grapher CGI script. + +=item B<--template>=I<TEMPLATE-FILE> + +Uses given file as a template. The template file must reside in @tmpldir@ +directory. It must be a Template-toolkit file, with the following variables +defined: + + tree Tree name + token Leaf token + path Leaf path + url URL for browsing this leaf + ncomment This leaf comment + npcomment Leaf's parent comment + event Event type + monitor Monitor name + mcomment Monitor comment + timestamp Time and date of the event + env(VAR) Environment variable VAR + +=back + +=head1 FILES + +=over 4 + +=item F<@siteconfdir@/email-siteconfig.pl> + +Torrus site email configuration script. + +=item F<@tmpldir@> + +=item F<@tmpluserdir@> + +Torrus template directories. + +=back + +=head1 SEE ALSO + +L<torrus(@mansec_usercmd@)> + +=head1 NOTES + +See more documentation at Torrus home page: http://torrus.org + +=head1 AUTHOR + +Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> diff --git a/torrus/doc/manpages/torrus_action_snmptrap.pod.in b/torrus/doc/manpages/torrus_action_snmptrap.pod.in new file mode 100644 index 000000000..409a9109e --- /dev/null +++ b/torrus/doc/manpages/torrus_action_snmptrap.pod.in @@ -0,0 +1,97 @@ +# Copyright (C) 2004 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: torrus_action_snmptrap.pod.in,v 1.1 2010-12-27 00:04:39 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 NAME + +action_snmptrap, action_snmpv1trap - Scripts for sending +SNMP traps (version 2c and 1 respectively) from monitor action. +C<action_snmpv1trap> is obsolete as the preferred SNMP version is 2c. + +=head1 SYNOPSIS + + <action name="snmptrap"> + <param name="action-type" value="exec" /> + <param name="command" value="$TORRUS_BIN/action_snmptrap" /> + <param name="launch-when" value="set, clear" /> + </action> + +=head1 DESCRIPTION + +This program is designed for usage from a monitor action only. It takes +the arguments from environment variables, as described in action-type +C<exec> in B<Torrus XML Configuration Guide>. In addition, some values +may be supplied via command-line arguments (see section OPTIONS below). + +Site-specific variables must be specified in the file +F<snmptrap-siteconfig.pl>. Default values are installed by the first run +of C<make install>. Subsequent +runs of C<make install> do not override this file. + +=head1 OPTIONS + +=over 4 + +=item B<--host>=I<HOSTNAME> + +Sets the hostname of the destination host. + +=item B<--community>=I<COMMUNITY> + +Sets the community string to use when sending the trap. + +=item B<--port>=I<PORT> + +Sets the destination UDP port. + +=item B<--enterprise>=I<OID> + +Sets the C<enterprise> field of the SNMPv1 trap to a given OID (see +RFC 1157 for more details). This option is only available for +C<action_snmpv1trap> and will be ignored for C<action_snmptrap>. + +=item B<--severity>=I<SEVERITY> + +Sets the optional severity SNMP variable to some integer value. + +=back + +=head1 FILES + +=over 4 + +=item F<@siteconfdir@/snmptrap-siteconfig.pl> + +Torrus site configuration script for SNMP traps. + +=back + +=head1 SEE ALSO + +L<torrus(@mansec_usercmd@)> + +=head1 NOTES + +See more documentation at Torrus home page: http://torrus.org + + +=head1 AUTHOR + +Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> diff --git a/torrus/doc/manpages/torrus_buildsearchdb.pod.in b/torrus/doc/manpages/torrus_buildsearchdb.pod.in new file mode 100644 index 000000000..a4984e61e --- /dev/null +++ b/torrus/doc/manpages/torrus_buildsearchdb.pod.in @@ -0,0 +1,79 @@ +# Copyright (C) 2007 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: torrus_buildsearchdb.pod.in,v 1.1 2010-12-27 00:04:39 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 NAME + +buildsearchdb - Build the search database + +=head1 SYNOPSIS + +B<torrus buildsearchdb> I<options...> + +=head1 DESCRIPTION + +This command indexes the Torrus configuration objects and builds the +search index database. One of the three options B<--tree>, B<--all> or +B<--global> is required. + +=head1 OPTIONS + +=over 4 + +=item B<--tree>=I<TREE> + +Build the indexes for a given tree. + +=item B<--all> + +Builds the tree indexes for all trees. + +=item B<--global> + +Builds the global index for all trees and also the tree indexes for every +tree. In order to use the global search database, the web user +should have the permission to display all trees and also it should have +the permission for GlobalSearch for all trees, for example: + + torrus acledit --addgroup=staff --permit=GlobalSearch --for='*' + + +=item B<--verbose> + +Prints extra information + +=item B<--help> + +Displays a help message. + +=back + +=head1 SEE ALSO + +L<torrus(@mansec_usercmd@)> + +=head1 NOTES + +See more documentation at Torrus home page: http://torrus.org + +=head1 AUTHOR + +Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> + diff --git a/torrus/doc/manpages/torrus_cleanup.pod.in b/torrus/doc/manpages/torrus_cleanup.pod.in new file mode 100644 index 000000000..d01b3e84a --- /dev/null +++ b/torrus/doc/manpages/torrus_cleanup.pod.in @@ -0,0 +1,60 @@ +# Copyright (C) 2004 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: torrus_cleanup.pod.in,v 1.1 2010-12-27 00:04:39 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 NAME + +cleanup - Cleans up Torrus web session data. + +=head1 SYNOPSIS + +B<torrus cleanup> + +=head1 DESCRIPTION + +This command cleans out the expired (older than 2 days) Torrus web interface +session data. + +=head1 FILES + +=over 4 + +=item F<@sesstordir@> + +Torrus session data storage directory. + +=item F<@seslockdir@> + +Torrus session data lock directory. + +=back + +=head1 SEE ALSO + +L<torrus(@mansec_usercmd@)> + +=head1 NOTES + +See more documentation at Torrus home page: http://torrus.org + +=head1 AUTHOR + +Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> + diff --git a/torrus/doc/manpages/torrus_clearcache.pod.in b/torrus/doc/manpages/torrus_clearcache.pod.in new file mode 100644 index 000000000..a9c5a5be3 --- /dev/null +++ b/torrus/doc/manpages/torrus_clearcache.pod.in @@ -0,0 +1,47 @@ +# Copyright (C) 2004 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: torrus_clearcache.pod.in,v 1.1 2010-12-27 00:04:38 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 NAME + +clearcache - Clears the Torrus Renderer's cache. + +=head1 SYNOPSIS + +B<torrus clearcache> + +=head1 DESCRIPTION + +This program clears Torrus Renderer's cache. It is intended for debugging +purposes only. + +=head1 SEE ALSO + +L<torrus(@mansec_usercmd@)> + +=head1 NOTES + +See more documentation at Torrus home page: http://torrus.org + + +=head1 AUTHOR + +Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> + diff --git a/torrus/doc/manpages/torrus_collector.pod.in b/torrus/doc/manpages/torrus_collector.pod.in new file mode 100644 index 000000000..071b308d9 --- /dev/null +++ b/torrus/doc/manpages/torrus_collector.pod.in @@ -0,0 +1,129 @@ +# Copyright (C) 2004 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: torrus_collector.pod.in,v 1.1 2010-12-27 00:04:38 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 NAME + +collector - Torrus data Collector. + +=head1 SYNOPSIS + +B<torrus collector> --tree=I<TREENAME> [I<options...>] + +=head1 DESCRIPTION + +This command starts the Collector process for the tree I<TREENAME>. By +default it forks into a daemon, sets the log output file to +F<@logdir@/collector.TREENAME.log>, performs one +Collector cycle, and sleeps until the next cycle is scheduled. In +daemon mode the log file can be reopened by sending it a SIGHUP +signal. + +Collector cycle scheduling is controlled by two parameters defined +for each individual configuration leaf: C<collector-period> and +C<collector-timeoffset>. See the B<Torrus Configuration Guide> for more +details. + +The number of OID (Object IDentifier) variable bindings sent by +Collector is controlled by the datasource parameter C<snmp-oids-per-pdu>. +It is set to a default value of 40 in F<snmp-defs.xml>, and may be +overwritten at the host level. + +=head1 OPTIONS + +=over 4 + +=item B<--instance>=I<N> + +Defines the collector instance. A single tree can allow more than one +collector instance. The number of instances is defined in C<run> hash +in the F<torrus-siteconfig.pl>'s C<%Torrus::Global::treeConfig>. +If the number of instances is more than one, this option is mandatory. +The collecting job is split between the instances, and normally all +instances should be started by the startup scripts. The tree should +be re-compiled after the number of instances is changed in the siteconfig. +In the example below the tree I<tree_A> will be served by three +collector instances: + + %Torrus::Global::treeConfig = ( + 'tree_A' => { + 'description' => 'The First Tree', + 'xmlfiles' => [qw(a1.xml a2.xml a3.xml)], + 'run' => { 'collector' => 3, 'monitor' => 1 } }, + ); + +=item B<--nodaemon> + +Prevents the process from becoming a daemon and sets the log to STDERR. + +=item B<--runonce> + +Instructs the collector to run once and exit. Implies B<--nodaemon>. + +=item B<--runalways> + +Instructs the collector process to continue running even if no collector +datasources are defined in the tree. In this case, the process will check +once per hour if the configuration has changed. + +=item B<--debug> + +Sets the log level to debug. + +=item B<--verbose> + +Sets the debug level to info. + +=item B<--help> + +Displays a help message. + +=back + +=head1 FILES + +=over 4 + +=item F<@siteconfdir@/torrus-siteconfig.pl> + +Torrus site configuration script. + +=item F<@logdir@/collector.TREENAME.log> + +Collector's log for the tree I<TREENAME>. + +=item F<@distxmldir@/snmp-defs.xml> + +Basic variable definitions for the SNMP collector. + +=back + +=head1 SEE ALSO + +L<torrus(@mansec_usercmd@)> + +=head1 NOTES + +See more documentation at Torrus home page: http://torrus.org + + +=head1 AUTHOR + +Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> diff --git a/torrus/doc/manpages/torrus_compilexml.pod.in b/torrus/doc/manpages/torrus_compilexml.pod.in new file mode 100644 index 000000000..281e1fbf2 --- /dev/null +++ b/torrus/doc/manpages/torrus_compilexml.pod.in @@ -0,0 +1,91 @@ +# Copyright (C) 2004 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: torrus_compilexml.pod.in,v 1.1 2010-12-27 00:04:39 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 NAME + +compilexml - Torrus XML configuration (re)compiler. + +=head1 SYNOPSIS + +B<torrus compilexml> --tree=I<TREENAME> [I<options...>] + +=head1 DESCRIPTION + +This command compiles the Torrus's XML configuration for the tree +I<TREENAME>. It does not require any other processes to be restarted +after the configuration is changed. Renderer's cache is automatically +flushed on on the next Renderer's run. Monitor automatically resets on +the next monitoring cycle. All dynamic tokensets in the given tree are +emptied. + +=head1 OPTIONS + +=over 4 + +=item B<--all> + +Instructs to compile configuration for all trees. + +=item B<--nods> + +Instructs to compile non-datasource configuration only. + +=item B<--noval> + +Disables all validation of the XML configuration. This speeds up the +compilation up to 2 times, while adding a risk to end up with an +unusable configuration. In addition, the first initialization cycle of +Collector and Monitor in this case would be much longer. + +=item B<--force> + +Normally the compiler would fail to start if another compiler process +is already running for the specific tree. In case of abnormal function, +the running status of the previous pcompiler may stay in the database. +This option forces the compiler to continue even if if sees the presence +of another process. + +=item B<--debug> + +Sets the log level to debug. + +=item B<--verbose> + +Sets the debug level to info. + +=item B<--help> + +Displays a help message. + +=back + +=head1 SEE ALSO + +L<torrus(@mansec_usercmd@)> + +=head1 NOTES + +See more documentation at Torrus home page: http://torrus.org + + +=head1 AUTHOR + +Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> diff --git a/torrus/doc/manpages/torrus_configinfo.pod.in b/torrus/doc/manpages/torrus_configinfo.pod.in new file mode 100644 index 000000000..7c561e304 --- /dev/null +++ b/torrus/doc/manpages/torrus_configinfo.pod.in @@ -0,0 +1,46 @@ +# Copyright (C) 2004 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: torrus_configinfo.pod.in,v 1.1 2010-12-27 00:04:39 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 NAME + +configinfo - Displays useful statistics for all Torrus trees. + +=head1 SYNOPSIS + +B<torrus configinfo> + +=head1 DESCRIPTION + +This command displays information on all available Torrus trees, including +the names of the trees, counts of leaves, subtrees, views, monitors and +actions, and other information. + +=head1 SEE ALSO + +L<torrus(@mansec_usercmd@)> + +=head1 NOTES + +See more documentation at Torrus home page: http://torrus.org + +=head1 AUTHOR + +Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> diff --git a/torrus/doc/manpages/torrus_configsnapshot.pod.in b/torrus/doc/manpages/torrus_configsnapshot.pod.in new file mode 100644 index 000000000..27231497c --- /dev/null +++ b/torrus/doc/manpages/torrus_configsnapshot.pod.in @@ -0,0 +1,144 @@ +# Copyright (C) 2004 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: torrus_configsnapshot.pod.in,v 1.1 2010-12-27 00:04:37 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 NAME + +configsnapshot - Generates a configuration snapshot for a Torrus tree. + +=head1 SYNOPSIS + +B<torrus configsnapshot> --tree=I<TREENAME> [I<options...>] + +=head1 DESCRIPTION + +This command generates a configuration snapshot from current +datasources for tree I<TREENAME>. The output is an XML file, ready for +compilation, representing all datasources, monitors and tokensets of a +given tree. The snapshot does not include view definitions. Templates +and file patterns are expanded inside the file. It does not require +any other XML configuration files, except for F<defaults.xml> and your +custom view definitions. + +B<Warning:> C<configsnapshot> from RRFW release 0.1.5 will not work +correctly with databases from previous releases. Use RRFW release +C<0.1.4bf2> instead. C<configsnapshot> utility from RRFW release 0.1.4bf2 +does not preserve aliases. + +This utility is useful in Torrus upgrade process. In case when RRD files +structure is changing in Torrus default templates, and user(s) demand to +preserve the historical data, the following steps could be done: + +=over 4 + +=item * + +Stop the collector and monitor processes. + +=item * + +Install newest Torrus software and do not run C<compilexml> immediately. + +=item * + +Create snapshots of the trees that you want to preserve for historical reasons: + + torrus configsnapshot --tree=myrouters \ + --out=@sitexmldir@/myrouters-snapshot.xml + +=item * + +If needed, move the existing RRD files into different directory. Then +change the C<data-dir> parameters in the snapshot XML accordingly. + +=item * + +Create a new tree with only the snapshot file in it. Compile the tree. + +=item * + +At this stage, it is up to the user to decide wether to continue running the +collector and monitor daemons for this new tree. The old data may be preserved +for historical reference, and collector may be run with the newest tree +structure and definitions. + +=back + +=head1 OPTIONS + +=over 4 + +=item B<--tree>=I<TREE> + +Mandatory parameter specifying the tree name. + +=item B<--out>=I<FILE> + +Sets the output file to I<FILE>. Default is F<snapshot.xml>. + +=item B<--param>=I<PARAM> B<--value>=I<VALUE> + +Sets the filter on datasource leaves that have to be included in the snapshot. +I<PARAM> specifies the name of the datasource parameter, and I<VALUE> +sets the matching value. By default the numeric comparison is performed. + +=item B<--op>=I<OPERATOR> + +Sets the fiter comparison operator. Accepted values: B<=> (numeric), +B<eq> (text string comparison), and B<re> (regular expression match). Default +is numeric comparison. + + +=item B<--verbose> + +Displays some extra information. + +=item B<--help> + +Displays a help message. + +=back + +=head1 FILES + +=over 4 + +=item F<@distxmldir@/defaults.xml> + +XML configuration file with default settings for the datasources and +tokensets, as well as default view definitions. + +=item F<snapshot.xml> + +Default B<configsnapshot> output file. + +=back + +=head1 SEE ALSO + +L<torrus(@mansec_usercmd@)>, L<torrus_compilexml(@mansec_usercmd@)> + +=head1 NOTES + +See more documentation at Torrus home page: http://torrus.org + +=head1 AUTHOR + +Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> diff --git a/torrus/doc/manpages/torrus_devdiscover.pod.in b/torrus/doc/manpages/torrus_devdiscover.pod.in new file mode 100644 index 000000000..452694208 --- /dev/null +++ b/torrus/doc/manpages/torrus_devdiscover.pod.in @@ -0,0 +1,114 @@ +# Copyright (C) 2004 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: torrus_devdiscover.pod.in,v 1.1 2010-12-27 00:04:39 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 NAME + +devdiscover - Performs SNMP discovery and generates Torrus XML +configuration file. + +=head1 SYNOPSIS + +B<torrus devdiscover> [--in=I<XMLFILE>] [I<options...>] [I<XMLFILES>] + +=head1 DESCRIPTION + +B<devdiscover> performs SNMP discovery using the I<XMLFILE> +for the discovery instructions. It generates a corresponding +Torrus XML configuration file. See B<Torrus SNMP Discovery User Guide> for +details. + +The generic input file, or device discovery XML (DDX), may be generated +by the B<genddx> utility, and then edited and maintained manually. +Multiple input files may be specified by several instances of I<--in> +option, or simply as arguments. + +Input file name is searched in the current directory, and then in +F<@sitedir@/discovery/>. + +=head1 OPTIONS + +=over 4 + +=item B<--mkdir> + +Creates C<data-dir> directories. + +=item B<--limit>=I<REGEXP> + +Limits the discovery to the output files matching the regular expression +I<REGEXP>. + +=item B<--forcebundle> + +With this option enabled, C<devdiscover> will write the bundle +file even if some of the bundle members were not created because of errors. + +=item B<--fallback>=I<INTEGER> + +Requires B<--forcebundle>. In case if an SNMP device is not available, +the bundle file will include an older version of the XML output file, +provided that it exists and it is not older than the specified number of days. + +=item B<--threads>=I<INTEGER> + +If the threads are enabled in the local Perl, this option determins +how many parallel discovery threads are to be executed. +The discovery jobs are distributed per output files, thus it makes +sence to use threads only when there are many output files defined in +a single DDX file. + + +=item B<--verbose> + +Prints extra information. + +=item B<--debug> + +Prints debugging information. + +=item B<--snmpdebug> + +Prints SNMP protocol details + +=back + +=head1 FILES + +=over 4 + +=item F<@siteconfdir@/devdiscover-siteconfig.pl> + +B<devdiscover> site configuration file. + +=back + +=head1 SEE ALSO + +L<torrus(@mansec_usercmd@)>, L<torrus_genddx>(@mansec_usercmd@) + +=head1 NOTES + +See I<Torrus SNMP Discovery User Guide> for more details at Torrus home +page: http://torrus.org + +=head1 AUTHOR + +Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> diff --git a/torrus/doc/manpages/torrus_flushmonitors.pod.in b/torrus/doc/manpages/torrus_flushmonitors.pod.in new file mode 100644 index 000000000..eec9a5f5b --- /dev/null +++ b/torrus/doc/manpages/torrus_flushmonitors.pod.in @@ -0,0 +1,68 @@ +# Copyright (C) 2010 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: torrus_flushmonitors.pod.in,v 1.1 2010-12-27 00:04:39 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 NAME + +flushmonitors - Flush monitor alarms and tokenset members + +=head1 SYNOPSIS + +B<torrus flushmonitors> --tree=I<TREENAME> [I<options...>] + +=head1 DESCRIPTION + +This command flushes the state of all monitor alarms for a given tree, +and also the tokenset members which were originated by the monitor alarms. + +=head1 OPTIONS + +=over 4 + +=item B<--all> + +Instructs to flush all trees. + +=item B<--debug> + +Sets the log level to debug. + +=item B<--verbose> + +Sets the debug level to info. + +=item B<--help> + +Displays a help message. + +=back + +=head1 SEE ALSO + +L<torrus(@mansec_usercmd@)> + +=head1 NOTES + +See more documentation at Torrus home page: http://torrus.org + + +=head1 AUTHOR + +Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> diff --git a/torrus/doc/manpages/torrus_genddx.pod.in b/torrus/doc/manpages/torrus_genddx.pod.in new file mode 100644 index 000000000..8fff69e49 --- /dev/null +++ b/torrus/doc/manpages/torrus_genddx.pod.in @@ -0,0 +1,136 @@ +# Copyright (C) 2004 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: torrus_genddx.pod.in,v 1.1 2010-12-27 00:04:38 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 NAME + +genddx - Generates SNMP discovery instructions file for +B<devdiscover> + +=head1 SYNOPSIS + +B<torrus genddx> --host=I<HOSTNAME> | --hostfile=I<HOSTFILENAME> \ +[I<options...>] + +=head1 DESCRIPTION + +B<genddx> generates the SNMP discovery instructions file, which may +be later used as input for the B<devdiscover> utility to produce the +corresponding Torrus XML configuration file. The hostname(s) of router(s) to +be included in SNMP discovery must be specified either using the +B<--host> (for a single router) or B<--hostfile> option. In the latter +case the file I<HOSTFILENAME> must contain a space-separated list of router +hostnames. Hostnames may have the form C<host:devname> where C<devname> is +a symbolic device name. + +This utility is designed to be used only once, in order to generate +the discovery XML canvas, for futher manual editing. It generates only +basic set of parameters, and there are much more of those that you may +use to customize the discovery process. + +See L<torrus_ttproclist(@mansec_usercmd@)> for a more flexible and +complex DDX generator. + +More information is available in B<Torrus SNMP Discovery User Guide>. + +=head1 OPTIONS + +=over 4 + +=item B<--out>=I<OUTFILENAME> + +Sets the output file to I<OUTFILENAME>. Default is F<routers.ddx>. Without +absolute path, the file will be placed in F<@sitedir@/discovery>. + +=item B<--discout>=I<FILENAME> + +Sets the discovery output file to I<FILENAME>. This will be the filename of +the Torrus XML configuration file once the output file of the B<genddx> +is processed by the B<devdiscover> utility. Default value is +F<routers.xml>. Without absolute path, the file would be resided in +F<@sitexmldir@>. + +=item B<--domain>=I<DOMAIN> + +Sets the DNS domain name to I<DOMAIN>. + +=item B<--version>=I<SNMPVERSION> + +Sets discovery SNMP version to SNMPVERSION. Default value is C<2c>. + +=item B<--community>=I<COMMUNITY> + +Sets discovery SNMP read community value to string I<COMMUNITY>. Default +is C<public>. + +=item B<--port>=I<PORT> + +Sets SNMP port to I<PORT>. Default is 161. + +=item B<--retries>=I<NUMRETRIES> + +Sets number of retries to I<NUMRETRIES>. Default value is 2. + +=item B<--timeout>=I<TIMEOUT> + +Sets SNMP timeout to I<TIMEOUT> seconds. Default value is 10. + +=item B<--subtree>=I<SUBTREE> + +Sets the subtree name to I<SUBTREE>. Default is C</Routers>. + +=item B<--datadir>=I<DATADIR> + +Sets the path of the directory where SNMP data is collected to I<DATADIR>. +Default value is F<@defrrddir@>. + +=item B<--holtwinters> + +Enables Holt-Winters analysis. + +=back + +=head1 FILES + +=over 4 + +=item F<@sitedir@/discovery/routers.ddx> + +Default output file of genddx. + +=item F<@sitexmldir@/routers.xml> + +Default Torrus XML configuration file which will be written once the +genddx output file is processed with devdiscover utility. + +=back + +=head1 SEE ALSO + +L<torrus(@mansec_usercmd@)>, L<torrus_devdiscover(@mansec_usercmd@)>, +L<torrus_ttproclist(@mansec_usercmd@)> + +=head1 NOTES + +See more documentation at Torrus home page: http://torrus.org + +=head1 AUTHOR + +Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> diff --git a/torrus/doc/manpages/torrus_genlist.pod.in b/torrus/doc/manpages/torrus_genlist.pod.in new file mode 100644 index 000000000..a3e112c56 --- /dev/null +++ b/torrus/doc/manpages/torrus_genlist.pod.in @@ -0,0 +1,71 @@ +# Copyright (C) 2004 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: torrus_genlist.pod.in,v 1.1 2010-12-27 00:04:39 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 NAME + +genlist - Lists Torrus objects + +=head1 SYNOPSIS + +B<torrus genlist> --tree=I<TREENAME> [I<options...>] + +=head1 DESCRIPTION + +This command generates a listing of objects in Torrus +configuration tree I<TREENAME>. Currently it lists the RRD files only. + +=head1 OPTIONS + +=over 4 + +=item B<--path>=I<PATH> + +Sets the subtree path to I<PATH>. Default values is "/". + +=item B<--what>=I<ITEMS> + +Includes items I<ITEMS> in the listing. Currently only "rrdfiles" is +a supported item. + +=item B<--type>=I<TYPE> + +Sets selection type. Currently supported values are "collector" (Collector +leaves), "readonly" (read-only leaves) and "all" (this also happens to be +default value). + +=item B<--help> + +Displays a help message. + +=back + +=head1 SEE ALSO + +L<torrus(@mansec_usercmd@)> + +=head1 NOTES + +See more documentation at Torrus home page: http://torrus.org + +=head1 AUTHOR + +Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> + diff --git a/torrus/doc/manpages/torrus_genreport.pod.in b/torrus/doc/manpages/torrus_genreport.pod.in new file mode 100644 index 000000000..8b7767166 --- /dev/null +++ b/torrus/doc/manpages/torrus_genreport.pod.in @@ -0,0 +1,93 @@ +# Copyright (C) 2007 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: torrus_genreport.pod.in,v 1.1 2010-12-27 00:04:39 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 NAME + +genreport - Generate the Usage Report + +=head1 SYNOPSIS + +B<torrus genreport> --report=I<ReportName> --date=I<YYYY-MM-DD> [I<options...>] +B<torrus genreport> --genhtml [I<options...>] + + +=head1 DESCRIPTION + +When the Torrus Reporting engine is set up, this command is used +to generate the reports from the collected data. +See I<Torrus Reporting Setup Guide> for more information. + +=head1 OPTIONS + +=over 4 + +=item B<--report>=I<ReportName> + +The name of the report that is to be generated. Currently supported: +C<MonthlyUsage>. + +=item B<--date>=I<YYYY-MM-DD> + +Specifies the start date of the reported period. For the monthly report, +this should be any day within the calendar month. + +=item B<--time>=I<hh:mm> + +Specifies the start time of the reported period. This option +is ignored for the monthly reports. + +=item B<--genhtml> + +Instructs the report engine to build the HTML output from the generated +reports. + +=item B<--tree=TREE> + +When used with C<--genhtml>, generates the HTML reports only for +the specified tree. + +=item B<--all2tree=TREE> + +When used with C<--genhtml>, generates the HTML reports only for +all available service IDs in the specified tree. + +=item B<--verbose> + +Prints extra informatgion. + +=item B<--debug> + +Prints debugging information. + +=back + +=head1 SEE ALSO + +L<torrus(@mansec_usercmd@)> + +=head1 NOTES + +See more documentation at Torrus home page: http://torrus.org + +=head1 AUTHOR + +Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> + diff --git a/torrus/doc/manpages/torrus_install_plugin.pod.in b/torrus/doc/manpages/torrus_install_plugin.pod.in new file mode 100644 index 000000000..3aeb0835e --- /dev/null +++ b/torrus/doc/manpages/torrus_install_plugin.pod.in @@ -0,0 +1,51 @@ +# Copyright (C) 2007 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: torrus_install_plugin.pod.in,v 1.1 2010-12-27 00:04:39 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 NAME + +install_plugin - Installs the Torrus plugin + +=head1 SYNOPSIS + +B<torrus install_plugin> I<DIRECTORY> + +=head1 DESCRIPTION + +This command installs a Torrus plugin. Prior to executing this command, +unpack the plugin package into some directory, and then point +C<install_plugin> to the path of the unpacked plugin distribution. + +The command would launch the C<./configure> script for the plugin +and supply all options that specify the current Torrus installation paths. +Then it would execute C<make> and C<make install>. + +=head1 SEE ALSO + +L<torrus(@mansec_usercmd@)> + +=head1 NOTES + +See more documentation at Torrus home page: http://torrus.org + +=head1 AUTHOR + +Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> + diff --git a/torrus/doc/manpages/torrus_monitor.pod.in b/torrus/doc/manpages/torrus_monitor.pod.in new file mode 100644 index 000000000..dabfc01b8 --- /dev/null +++ b/torrus/doc/manpages/torrus_monitor.pod.in @@ -0,0 +1,96 @@ +# Copyright (C) 2004 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: torrus_monitor.pod.in,v 1.1 2010-12-27 00:04:38 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 NAME + +monitor - Torrus Monitor. + +=head1 SYNOPSIS + +B<torrus monitor> --tree=I<TREENAME> [I<options...>] + +=head1 DESCRIPTION + +This command starts the Monitor process for the tree I<TREENAME>. By +default it forks into a daemon, sets the log output file to +F<@logdir@/monitor.TREENAME.log>, performs one monitoring cycle, and +sleeps until the next cycle is scheduled. In daemon mode the log file +can be reopened by sending it a SIGHUP signal. + +=head1 OPTIONS + +=over 4 + +=item B<--nodaemon> + +Prevents the process from becoming a daemon and sets the log to STDERR. + +=item B<--runonce> + +Instructs the script to run once and exit. Implies B<--nodaemon>. + +=item B<--delay=N> + +Makes the daemon sleep for N minutes before starting the first cycle. +This would happen on the daemon startup and also after each configuration +recompilation. +For example, when monitor and collector start simultaneously, the collector +needs some time to retrieve the data being monitored. + +=item B<--debug> + +Sets the log level to debug. + +=item B<--verbose> + +Sets the debug level to info. + +=item B<--help> + +Displays a help message. + +=back + +=head1 FILES + +=over 4 + +=item F<@siteconfdir@/torrus-siteconfig.pl> + +Torrus site configuration script. + +=item F<@logdir@/monitor.TREENAME.log> + +Monitor's log for the tree I<TREENAME>. + +=back + +=head1 SEE ALSO + +L<torrus(@mansec_usercmd@)> + +=head1 NOTES + +See more documentation at Torrus home page: http://torrus.org + +=head1 AUTHOR + +Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> diff --git a/torrus/doc/manpages/torrus_nodeid.pod.in b/torrus/doc/manpages/torrus_nodeid.pod.in new file mode 100644 index 000000000..f80664e11 --- /dev/null +++ b/torrus/doc/manpages/torrus_nodeid.pod.in @@ -0,0 +1,124 @@ +# Copyright (C) 2010 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: torrus_nodeid.pod.in,v 1.1 2010-12-27 00:04:39 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 NAME + +nodeid - Torrus utility + +=head1 SYNOPSIS + +B<torrus nodeid> --tree=I<TREENAME> --cmd=CMD I<options...> + +=head1 DESCRIPTION + +This command provides a way to integrate Torrus with external OSS systems. +It operates with I<nodeid>, a unique identifier for Torrus datasource +subtrees and leaves. + +The command prints the data on the standard output in JSON data format. + +=head1 OPTIONS + +=over 4 + +=item B<--tree=TREE> + +[Mandatory] Defines the datasouerce tree. + + +=item B<--cmd=CMD> + +[Mandatory] Defines the action command. The following commands are supported: + +=over 8 + +=item * info + +Prints information about the nodeid. Requires B<--nodeid>. + +=item * search + +Performs a prefix or substring search on node IDs and prints the results. +Requires B<--prefix> or B<--substring>. + +=item * render + +Renders a specified datasource node and prints the resulting MIME type and the +file name. Requires B<--nodeid> and B<--view>. Optional B<--out> defines +a file name to copy the output to. + +=back + + +=item B<--nodeid=NODEID> + +Specifies the Node ID string for the commands I<info> and I<render>. + + +=item B<--details> + +Toggles verbose output for the commands I<info> and I<search>. + + +=item B<--prefix=STR> + +Specifies the prefix search string for the command I<search>. + + +=item B<--substring=STR> + +Specifies the search substring for the command I<search>. + + +=item B<--view=VIEW> + +Specifies the view name for the command I<render>. The following views are +defined by standard Torrus XML files and render a PNG graph: +C<short>, C<last24h-small>, C<last24h>, C<lastweek>, +C<lastmonth>, C<lastyear>. The following views are printing the datasource +value in a text format: C<rrd-print-daily>, C<rrd-print-last>. + + +=item B<--out=FILE> + +If defined, instructs the utility to copy the rendered data into a +specified file. Otherwise the file is created in the standard renderer's cache +directory. + + +=item B<--help> + +Displays a help message. + +=back + + +=head1 SEE ALSO + +L<torrus(@mansec_usercmd@)> + +=head1 NOTES + +See more documentation at Torrus home page: http://torrus.org + +=head1 AUTHOR + +Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> diff --git a/torrus/doc/manpages/torrus_rrddir2xml.pod.in b/torrus/doc/manpages/torrus_rrddir2xml.pod.in new file mode 100644 index 000000000..bd78e48ae --- /dev/null +++ b/torrus/doc/manpages/torrus_rrddir2xml.pod.in @@ -0,0 +1,112 @@ +# Copyright (C) 2004 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: torrus_rrddir2xml.pod.in,v 1.1 2010-12-27 00:04:38 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 NAME + +rrddir2xml - Searches a directory for RRD files and generates Torrus XML +configuration file. + +=head1 SYNOPSIS + +B<torrus rrddir2xml> --dir=I<DIR> [I<options...>] + +=head1 DESCRIPTION + +B<rrddir2xml> searches in a given directory for RRD files and +creates Torrus XML configuration file suitable for browsing ofthose data +files. + +With default options, it is usable for RRD files generated by Torrus' +SNMP collector, where the file name starts with the host name, separated by +underscore from interface name or other MIB specifics. With these +defaults, it creates a subtree per each host name, and all RRD files belonging +top that host name are sorted alphabetically in that subtree. + +=head1 OPTIONS + +=over 4 + +=item B<--dir>=I<DIR> + +Absolute path to the directory for searching. The directory may contain also +non-RRD files. Only regular files are processed, and the symlinks are ignored. + +=item B<--recursive> + +If specified, the directory will be searched recursively. All file names +across all subdirectories must be unique. Symlinks to other directories +are ignored. + +=item B<--filter>=I<Regexp> + +If the filter is specified, then B<rrddir2xml> lists only those files and +subdirectories whose names match the given regular expression. + +=item B<--out>=I<FILE> + +Output XML file name. If relative path given, the file is placed in +F<@sitexmldir@>. Default: F<rrddir.xml>. + +=item B<--subtree>=I<SUBTREE> + +Top subtree path in the generted XML. Default is the top of the tree (C</>). + +=item B<--split>=I<REGEXP> + +Regular expression used for splitting the file name into parts +to build the subtree hierarchy. Default is a sequence of underscores (C<_+>). + +=item B<--levels>=I<INTEGER> + +Number of levels of hierarchy to build by splitting the file names. +Default is 2 levels. + +=item B<--comment>=I<TEXT> + +Text to put as C<comment> parameter to the top subtree. + +=item B<--holtwinters> + +If specified, Holt-Winters prediciton boundaries and failures are displayed +in the graphs. + +=item B<--verbose> + +Prints extra diagnosics. + +=item B<--debug> + +Prints debugging information. + +=back + + +=head1 SEE ALSO + +L<torrus(@mansec_usercmd@)> + +=head1 NOTES + +See more documentation at Torrus home page: http://torrus.org + +=head1 AUTHOR + +Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> diff --git a/torrus/doc/manpages/torrus_schedulerinfo.pod.in b/torrus/doc/manpages/torrus_schedulerinfo.pod.in new file mode 100644 index 000000000..e8567a10b --- /dev/null +++ b/torrus/doc/manpages/torrus_schedulerinfo.pod.in @@ -0,0 +1,154 @@ +# Copyright (C) 2004 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: torrus_schedulerinfo.pod.in,v 1.1 2010-12-27 00:04:39 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 NAME + +schedulerinfo - Displays extended scheduler tasks information. + +=head1 SYNOPSIS + +B<torrus schedulerinfo> --tree=I<TREENAME> [I<options...>] + +=head1 DESCRIPTION + +This utility displays the extended scheduler tasks information for tree +I<TREENAME> on standard output. This might be useful for scheduler planning +and analysis. + +=head1 OPTIONS + +=over 4 + +=item B<--config> + +Reports scheduler's configuration. The values are explained below. + +=over 8 + +=item Total collector/monitor leaves: I<N> + +Total number of datasources being processed by collector or monitor daemon. + +=item Scheduled leaves by type + +Torrus supports arbitrary number of collector types, and this report +shows how many datasources belong to every type. Currently the monitor leaves +are not divided into types. + +=item Least common period: I<N> seconds + +The report below shows how the tasks are distributed across the time line, +and the least common period shows the period of this time line. + +=item Tasks execution timeline + +This report tells which task and how many datasources are involved in +each task startup event, and how these events are dispersed across the time. +The column I<Interval> shows the time interval from each task execution +event to the next event on the timeline. + +=back + +=item B<--runtime> + +Reports scheduler's runtime statistics, such as running cycle times, +late starts etc. The meaning of the output values is as follows. Values +that have zero values are usually not printed. + +=over 8 + +=item Task: I<Name>, Period: I<N> seconds, Offset: I<M> seconds + +Each scheduler task is characterized by its name (usually Collector or +Monitor), period, and timeoffset. Fore example, if period is set to 300 +seconds, and offset is 14 seconds, then the task would be executed at +00:00:14, 00:05:14, 00:10:14, and so on for every hour in a day. + +=item I<N> running cycles passed + +How many times the task was executed since last reset. The counter +is normally reset after L<torrus_compilexml(@mansec_usercmd@)> successfully +compiles the configuration. + +=item I<N> late starts + +How many times the task has started with a delay from its normal schedule. + +=item I<N> too long runs + +How many times the task execution time was longer than its period. + +=item I<N> overrun periods + +How many periods have been missed because of too long executions. + +=item I<N> missed periods + +How many periods were missed because of any reason (such as other tasks +delaying). + +=item Min, Max, Average, Exp Average + +The time values are displayed in four columns: Mimimum, Maximum and Average +values since last reset, and Exponential decay value, which may be interpreted +as the average for last several values. With defaults defined in +F<torrus-config.pl>, 95% of the average is calculated from last 3 values. + +=item Running Time + +How long the task executes each period. + +=item Late Start + +How long the task start was delayed. + +=item Too Long + +How much time the too long run took. + +=item RRD Queue + +In a multithreaded environment, the RRD files are writen in a background +thread. This value shows the length of the RRD update queue at the beginning +of each update cycle. + +=back + +=item B<--help> + +Displays a help message. + +=back + + + +=head1 SEE ALSO + +L<torrus(@mansec_usercmd@)>, +L<torrus_compilexml(@mansec_usercmd@)> + +=head1 NOTES + +See more documentation at Torrus home page: http://torrus.org + +=head1 AUTHOR + +Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> diff --git a/torrus/doc/manpages/torrus_snmpfailures.pod.in b/torrus/doc/manpages/torrus_snmpfailures.pod.in new file mode 100644 index 000000000..e458b62dc --- /dev/null +++ b/torrus/doc/manpages/torrus_snmpfailures.pod.in @@ -0,0 +1,155 @@ +# Copyright (C) 2010 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: torrus_snmpfailures.pod.in,v 1.1 2010-12-27 00:04:37 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 NAME + +snmpfailures - Displays SNMP collector failures. + +=head1 SYNOPSIS + +B<torrus snmpfailures> --tree=I<TREENAME> [I<options...>] + +=head1 OPTIONS + +=over 4 + +=item B<--details> + +In addition to failure counters, list the failed SNMP hosts and the time +stamps of failure events. + + +=item B<--help> + +Displays a help message. + +=back + +=head1 DESCRIPTION + +This utility prints the SNMP collector failure information in JSON format. +Without B<--details> option, it prints only the failure counters. + +Upon collector startup or after the tree re-compilation, the failure +counters are reset to zero. + +The output is very convenient for further automatic processing in any +scripting language. + +The top level of the output is a JSON object with the following name/value +pairs: + +=over 4 + +=item B<total_unreachable>: NUMBER + +Displays the number SNMP hosts that are currently unreachable. +The number adds up across multiple collector instances for a given tree. +If a host becomes reachable again, the number is decreased. + +=item B<total_deleted>: NUMBER + +Displays the number SNMP hosts that are completely removed from SNMP +collection for the life cycle of the collector process. This happens when +a host is unreachable for too long time and the collector gives up +to reach it again. +The number adds up across multiple collector instances for a given tree. + +=item B<total_mib_errors>: NUMBER + +Displays the number of MIB errors (I<noSuchObject>, I<noSuchInstance>, +and I<endOfMibView>) during the collector life cycle. +The number adds up across multiple collector instances for a given tree. + +=item B<detail_unreachable>: OBJECT, B<detail_deleted>: OBJECT + +If the option B<--details> is specified, these objects contain the host names +and timestamps of the failures. +The keys are contactenations of SNMP host, UDP port, and SNMP +community separated by "|". +The values are objects representing the UNIX timestamp and a human-readable +time string. + +=item B<detail_mib_errors>: OBJECT + +If the option B<--details> is specified, this object displays the MIB error +details: for each SNMP host, it lists the datasource leaves which had these +errors and the event timestamps. + +=back + +=head1 EXAMPLES + +The following example illustrates an SNMP host unreachable: + + torrus failures --tree=main --details + { + "detail_deleted" : {}, + "detail_mib_errors" : {}, + "detail_unreachable" : { + "217.101.101.101|161|public" : { + "time" : "Fri Jul 23 14:15:10 2010", + "timestamp" : 1279887310 + } + }, + "total_deleted" : 0, + "total_mib_errors" : 0, + "total_unreachable" : 1 + } + + +The following example illustrates a MIB error: + + torrus failures --tree=main --details + { + "detail_deleted" : {}, + "detail_mib_errors" : { + "217.101.102.102|161|public" : { + "count" : 1, + "nodes" : { + "/Routers/CMTS3/Temperature_Sensors/sensor_01" : { + "time" : "Fri Jul 23 15:26:14 2010", + "timestamp" : 1279891574 + } + } + } + }, + "detail_unreachable" : {}, + "total_deleted" : 0, + "total_mib_errors" : 1, + "total_unreachable" : 0 + } + + + + + +=head1 SEE ALSO + +L<torrus(@mansec_usercmd@)>, + +=head1 NOTES + +See more documentation at Torrus home page: http://torrus.org + +=head1 AUTHOR + +Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> diff --git a/torrus/doc/manpages/torrus_srvderive.pod.in b/torrus/doc/manpages/torrus_srvderive.pod.in new file mode 100644 index 000000000..a8c68c254 --- /dev/null +++ b/torrus/doc/manpages/torrus_srvderive.pod.in @@ -0,0 +1,136 @@ +# Copyright (C) 2007 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: torrus_srvderive.pod.in,v 1.1 2010-12-27 00:04:39 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 NAME + +srvderive - Derive a new service ID from sum or maximum of other service values + +=head1 SYNOPSIS + +B<torrus srvderive> I<TIMESPAN> I<OUTPUT> I<FUNCTION> I<SOURCES>... + +=head1 DESCRIPTION + +When the Torrus Reporting engine is set up, this command is used +to combine several services data into a new service ID. The output data +is either the maximum or the sum of input services. + +See I<Torrus Reporting Setup Guide> for more information. + +=head1 TIMESPAN + +Either --month or --end option must be defined + +=over 4 + +=item B<--start>=I<YYYY-MM-DD> + +Sets the start date of the calculation. + +=item B<--end>=I<YYYY-MM-DD> + +Sets the next day after the eond of the period. + +=item B<--month> + +Instead of setting the end data, it is convenient to use this option. It sets +the end data in one calendar month after the start date. + +=back + + +=head1 OUTPUT + +=over 4 + +=item B<--out>=I<SERVICEID> + +Sets the output service ID. This should not be a service ID used in the +Torrus datasource trees. B<Note:> if I<srvderive> command is run twice +with the same arguments, the produced data is doubled for the output +service ID. + +=back + + + +=head1 FUNCTION + +=over 4 + +=item B<--func>=C<MAX>|C<SUM> + +Sets the function to be used when combining the input service data. +Currently only C<MAX> and C<SUM> are supportted. + +=back + + +=head1 SOURCES + +=over 4 + +=item B<--in>=I<SERVICEID> ... + +Input service IDs are specified either by B<--in> option, or as command line +arguments. At least 2 input service IDs should be specified. + +=back + + + +=head1 OPTIONS + +=over 4 + +=item B<--step> + +Default: 300. Sets the data interval for derived service ID. It is recommended +to leave this option at default value. + +=item B<--verbose> + +Prints extra informatgion. + +=item B<--debug> + +Prints debugging information. + +=item B<--help> + +Prints command usage information. + +=back + + + +=head1 SEE ALSO + +L<torrus(@mansec_usercmd@)> + +=head1 NOTES + +See more documentation at Torrus home page: http://torrus.org + +=head1 AUTHOR + +Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> + diff --git a/torrus/doc/manpages/torrus_ttproclist.pod.in b/torrus/doc/manpages/torrus_ttproclist.pod.in new file mode 100644 index 000000000..db2100a83 --- /dev/null +++ b/torrus/doc/manpages/torrus_ttproclist.pod.in @@ -0,0 +1,144 @@ +# Copyright (C) 2004 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: torrus_ttproclist.pod.in,v 1.1 2010-12-27 00:04:39 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 NAME + +ttproclist - Process a template with a nodelist + +=head1 SYNOPSIS + +B<torrus ttproclist> --tmpl=I<TFILE> --out=I<OFILE> +--nodes=I<NFILE> [I<options...>] + +=head1 DESCRIPTION + +This command takes a Template-Toolkit template and a list of nodes +(usually SNMP devices) as input. The output file is a result of +template substitution, according to the specified options. +Command-line options B<--tmpl>, B<--out> and B<--nodes> are mandatory. + +This utility can be used to generate the discovery instructions XML out of +a predefined template and a dynamically generated list of devices. +Alternatively, it can produce Torrus XML configuration for a given list +of objects, etc. + +The following variables are predefined when the template is processed: + +=over 4 + +=item * C<nodes> + +Hash array of nodes. Hash keys are the node names. Values are symbolic +names. If symbolic names are not defined, values are the same as keys. + +=item * C<param> + +Hash array of command-line parameters given in B<--param> option. + +=item * C<nodesfile>, C<creator> + +Informative variables. They can be used to produce the creation +note in the resulting files. C<nodesfile> returns the file name of nodes, +and C<creator> returns a detailed information how the file was generated, +with timestamp and command line options. + +=back + +=head1 OPTIONS + +=over 4 + +=item B<--tmpl>=I<TFILE> + +The file name of the input template. Relative names are looked in +the current directory and in F<@tmpluserdir@>. The file name may also be +an absolute path. + +=item B<--out>=I<OFILE> + +Output file name. If no absolute path given, the file is written in the current +directory. + +=item B<--nodes>=I<NFILE> + +The name of the nodes list. Nodes should be separated by space or tab +character or newline. Additional information, referred to as symbolic name, +can be supplied after a colon, of the form NODENAME:SYMBOLICNAME. + +=item B<--param>=I<NAME:VALUE,NAME:VALUE...> + +List of optional parameters that may be used in the template. + +=back + +=head1 EXAMPLES + +The following example gerenates C<devdiscover> input file from a template. +The template is as follows: + + <?xml version="1.0" encoding="UTF8"?> + <snmp-discovery> + >>> usual DDX parameters here, like SNMP community and data-dir + <param name="snmp-community" value="private"/> + <param... + >>> This loop generates per-host entries + [% FOREACH n = nodes.keys.sort %] + <host> + <param name="snmp-host" value="[% n %]"/> + <param name="symbolic-name" value="[% nodes.$n %]"/> + <param name="output-file" value="nodes/[% n %].xml"/> + </host> + [% END %] + >>> Generate the bundle file, so that you need only one + >>> entry in torrus-site-config.pl + <param name="output-bundle" value="[% param.BUNDLE %].xml"/> + </snmp-discovery> + +The following command would generate F<MY.ddx> from template file F<MY.ddtmpl> +as described above. The file F<MY.nodes> is a list of SNMP devices, one per +line. Then C<devdiscover> is launched with F<MY.ddx> as input. Note also the +short form of the command line wrapper. + + torrus ttproclist --tmpl=MY.ddtmpl \ + --nodes=MY.nodes \ + --out=/usr/local/etc/torrus/discovery/MY.ddx \ + --param=BUNDLE:MYNODES + + torrus dd --in=MY.ddx --verbose + +In addition, you may put some common parameters in Template BLOCK +statement in a separate file, and INCLUDE it in your templates. See the +Template-Toolkit documentation for more detail. + + +=head1 NOTES + +See more documentation at Torrus home page: http://torrus.org + +=head1 SEE ALSO + +Template-Toolkit documentation: http://template-toolkit.org/ + +L<torrus(@mansec_usercmd@)>, L<torrus_devdiscover(@mansec_usercmd@)> + +=head1 AUTHOR + +Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> diff --git a/torrus/doc/nodeid_usage.pod.in b/torrus/doc/nodeid_usage.pod.in new file mode 100644 index 000000000..7f33a3704 --- /dev/null +++ b/torrus/doc/nodeid_usage.pod.in @@ -0,0 +1,210 @@ +# Copyright (C) 2010 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: nodeid_usage.pod.in,v 1.1 2010-12-27 00:04:35 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 Torrus/OSS integration: NodeID usage guidelines + +=head2 Introduction + +Most parts of Torrus software mentioned in this document were developed under +sponsoring by the following companies: + +=over 4 + +=item * nexellent ag, Switzerland (www.nexellent.ch) + +NodeID concept and base implementation, host-based authentication. + +=item * M-net Telekommunikations GmbH, Germany (www.m-net.de) + +M-net plugin. + +=item * Fibre Noire Internet Inc, Canada (www.fibrenoire.ca) + +Extensions in M-Net plugin for NodeID manipulation. + +=back + + + +This document explains the new concept of NodeID and ways of utilizing +it for better integration of Torrus into an OSS environment. + + +=head2 NodeID concept + +Torrus 1.0.9 introduces a new parameter for datasource tree elements: +C<nodeid>. This parameter is not inherited from parent subtrees to child +subtrees or leaves. Also the XML configuration compiler verifies uniqueness +of its values across the whole tree. + +The purpose of C<nodeid> is to provide persistent identifiers to the tree +elements. Unlike the token numbers, these identifiers are not changing between +re-compilations of the tree. Also unlike the path string, C<nodeid> would +stay the same if a network device changes its place in the tree topology. + +By default, C<nodeid> value is composed of SNMP host name and device +component name, such as IF-MIB interface. It can also be easily adapted to +contain external identifiers, such as Asset ID or Service ID from some +external inventory database. + +Once C<nodeid> values are put into the XML configuration (usually +SNMP discovery engine does it) and compiled into the configuration database, +they can be used for accessing the Torrus graphs from external systems. + +The command-line utility C<torrus nodeid> helps searching through existing +NodeID values, and also renders the graphs on request. + +Another quick way to find the NodeID value is to navigate to the desired +graph page and check the I<Bookmark> shortcut at the bottom of the page. +For the nodes where C<nodeid> is defined, the bookmark will use it instead of +the path in the datasource tree. + + + +=head2 Host-based authentication + +Many Torrus deployments have user authentication enabled. This makes it +complicated for other OSS systems to retrieve graphs from the Torrus rendering +engine. + +Torrus 1.0.9 introduces host-based authentication: a special user +is created for requestor's IP address. The requestor specifies its unique +password in the URL as C<hostauth> parameter. Also the Torrus WebUI does not +send the session cookie back to the requestor. + +This new feature makes it easy to display Torrus graphs inside user +self-service portals without giving direct access to the Torrus server. + +For example, the following command adds the host 10.0.0.5 with password +"654321" to the I<admin> group: + + torrus acl --addhost=10.0.0.5 --hostpassword=654321 --addtogroup=admin + +Then the following command executed from 10.0.0.5 would retrieve an +InOut_bps graph for the last 24 hours for a given interface on I<rtr01> router: + + wget -O graph.png \ + 'http://torrus/main?nodeid=if//rtr01//GigabitEthernet0/1//inoutbit&view=last24h&hostauth=654321' + + +=head2 M-net plugin + +Details of M-net plugin are explained in the plugin documentation. +The plugin interprets description strings on device network interfaces: +it catches all key-value pairs of format I<key1=val1;key2=val2;...> and +performs various actions on them. + +Now assume there's an external inventory system, and each network interface is +assigned a unique Asset ID. Our natural wish would be to use these asset IDs +in NodeID strings, instead of hostnames and interfaces. This way we are +secured against hardware changes and upgrades (assuming that Asset ID stays +unchanged). + +In order to take advantage of M-Net plugin, the Asset ID values should be +configured in all interface descriptions, like follows: + + interface GigabitEthernet0/1 + description bw=200M; assetid=VPNLINK00055; ct=BC + +In the example above, the interface description tells that this is a 200Mbps +link, connection type is Business Customer, and the unique link identifier is +I<VPNLINK00055>. The format allows inserting extra spaces for better +readability. + +In the corresponding Device Discovery XML (DDX) file, the following +parameters would be set: + + <host> + <param name="snmp-host" value="rtr01.example.com"/> + <param name="M_net::manage" value="yes"/> + <param name="M_net::nodeid-prefix-key" value="assetid"/> + </host> + +As a result, after the SNMP discovery and XML compiler finish their work, +we get a number of NodeID values associated with this customer connection: + + assetid//VPNLINK00055 + assetid//VPNLINK00055//inbytes + assetid//VPNLINK00055//indrops + assetid//VPNLINK00055//inerr + assetid//VPNLINK00055//inoutbit + assetid//VPNLINK00055//inpackets + assetid//VPNLINK00055//outbytes + assetid//VPNLINK00055//outdrops + assetid//VPNLINK00055//outerr + assetid//VPNLINK00055//outpackets + +The first NodeID refers to the interface-level subtree in Torrus +configuration, and all other values refer to the corresponding graphs +for this interface. + +So, now the customer self-service portal would retrieve the input/output +summary graph with the following URL (wget woulld be certainly replaced by a +corresponding command in PHP or other Web programming language): + + wget -O graph.png \ + 'http://torrus/main?nodeid=assetid//VPNLINK00055//inoutbit&view=last24h&hostauth=654321' + +Of course, a number of additional view definitions could be created, in order +to create graphs of needed size and time span. Also, for example, a calendar +month's graph could be generated by specifying the followiong +parameters in the URL: C<NOW> or C<Gend> pointing to the beginning of +next month, and optionally C<Gstart> indicating the start of the time period. + + +=head2 Setting the host identifier + +Alternatively to the technique explained above, the local OSS environment +could require some custom identifiers assigned to the network devices. +For example, CA Spectrum software uses its internal Model Handles to refer to +devices. + +The discovery parameter C<nodeid-device> sets the string that would be used +in the host part of NodeID values: + + <host> + <param name="snmp-host" value="rtr02.example.com"/> + <param name="nodeid-device" value="0xC0FFEE"/> + </host> + +The resulting NodeID values would be based on "0xC0FFEE" string instead of +"rtr02.example.com": + + if//0xC0FFEE//GigabitEthernet0/1//inoutbit + + +=head2 Future development + +The NodeID is a relatively new concept in Torrus, and there will be other +ways of specifying and using it in the course of Torrus development. + +One of the directions for future enhancement is a look-up of NodeID values +in some external database before or during SNMP discovery. + +The usage of NodeID is not limited to IF-MIB interfaces. Some Torrus +templates already assign NodeID values to, for example, environment sensors +and DOCSIS statistics. + + + +=head1 Author + +Copyright (c) 2010 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> diff --git a/torrus/doc/reporting_setup.pod.in b/torrus/doc/reporting_setup.pod.in new file mode 100644 index 000000000..5ff1118b8 --- /dev/null +++ b/torrus/doc/reporting_setup.pod.in @@ -0,0 +1,365 @@ +# webintf.pod - Torrus web interface reference +# Copyright (C) 2002 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: reporting_setup.pod.in,v 1.1 2010-12-27 00:04:34 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + + +=head1 Torrus Reporting Setup Guide + +In version 1.0.4, Torrus introduces a new and important functionality. +Now it is able to produce reports that may be used in billing or +resource planning. The reports are meant to be text output, telling +the bandwidth usage or volume: no graphs so far. + +By default, the reporting functionality is not enabled, and the steps +required are described below. + + +=head2 Terminology + +The basic term in Torrus reporting is the B<Service ID>. +It denotes a single datasource that is represented by a single number. +For example, if you want to count input and output interface traffic, +this would make two different service IDs. Do not assign service IDs +to each and every interface in your network, as it would degrade +the performance of your Torrus installation significantly. +This functionality is designed for use with important datasources, +such as your customers' connection links or and ISP's upstream channels. + +Each service ID must be B<unique> across the whole Torrus installation, +and across the database that stores them (it is possible to use +several Torrus installations with the same database). + +B<Devdiscover>, the SNMP discovery engine, allows now to assign +service IDs to network interfaces of your SNMP-enabled devices. +However, this does not prevent you from assigning them to other Torrus +datasources, as it's done by simple configuration parameters. + +B<Report>, when generated, is presented by a set of numeric values +in the SQL database. Torrus provides also tools for rendering these +values into HTML B<output>. In the future, other output formats +will be implemented. You can also build your own infrastructure that +reads the values from the reports database. + +The produced reports may, and are primarily developed for using in +B<billing> process. As it is stated in the GNU General Public License +text, this program is provided "as is" and B<without warranty of any kind>. +It is up to the users of Torrus software to rely or not to rely on +the generated numeric data, and the Torrus software developers disclaim +any responsibility for the data accuracy and usability. + + +B<New in version 1.0.7:> You can assign the list of trees where the reports +should be generated and shown. B<Warning:> after changing the destination tree, +the compiler may complain about I<duplicate service IDs>. Then you need to +stop all the torrus processes, including Apache, and then remove the file +F<serviceid_params.db> from Torrus database directory, then recompile the +trees and start the processes. + + +=head2 Install Perl modules + +Install the following Perl modules from CPAN: + + DBI + DBD::mysql or other RDBMS driver + DBIx::Abstract + DBIx::Sequence + +On many platforms, DBI is already pre-installed. You need to make sure +that appropriate DBD driver is installed for your database engine. +The setup was tested with MySQL, SQL syntax is compatible with Postgres, +and in theory it should run also with Oracle and probably Sybase or DB2. +No idea about MSSQL - if you're brave enough, let me know if it works :) + + +=head2 Enable the External Storage and specify the SQL connection + +In F<torrus-siteconfig.pl>, add the following lines. The first one +tells the collector to use the module for storing the collector results in +SQL database. Next lines define the database connection. By default, +it refers to the MySQL database named C<torrus> on C<localhost>, +with username and password set to C<imiF1oih>. + + + push(@Torrus::Collector::loadModules, 'Torrus::Collector::ExternalStorage'); + $Torrus::SQL::connections{'Default'}{'dsn'} = + 'DBI:mysql:database=torrus;host=dbhost.example.com'; + $Torrus::SQL::connections{'Default'}{'username'} = 'torrus'; + $Torrus::SQL::connections{'Default'}{'password'} = 'imiF1oih'; + +In addition to the default connection, you can specify different connections +for different data structures: for example, keep 5-minutes samples on +a bulky storage server, and store the reports on a high-availability cluster. +See the comments in F<torrus-config.pl> for more details. + + +=head2 Create SQL tables + +With your RDBMS client, create the following tables. We assume here that +the same database is used for all tables. The SQL syntax is verified with +MySQL 4.x and Postgres 8.x. It is brought as much as possible to +the standard and platform-independent SQL syntax. Please let me know +if it causes problems with your RDBMS. + + + /* Collector export table. It usually grows at several megabytes + per month, and is updated every 5 minutes */ + CREATE TABLE srvexport + ( + srv_date DATE NOT NULL, /* date and time of the data sample */ + srv_time TIME NOT NULL, + serviceid VARCHAR(64) NOT NULL, /* unique service ID per counter */ + value DOUBLE PRECISION NOT NULL, /* collected rate or gauge value */ + intvl INTEGER NOT NULL /* collection interval - + for counter volume calculation */ + ); + CREATE INDEX srvexp_date ON srvexport (srv_date); + CREATE INDEX srvexp_srvid ON srvexport (serviceid); + + + /* Tables for (currently monthly only) report contents. + These are updated usually once per month, and read at the moment of + rendering the report output (HTML now, PDF or XML or Excel or whatever + in the future) */ + + /* DBIx::Sequence backend, theplatform-independent inplementation + of sequences */ + CREATE TABLE dbix_sequence_state + ( + dataset varchar(50) NOT NULL, + state_id INTEGER NOT NULL, + CONSTRAINT pk_dbix_sequence PRIMARY KEY (dataset, state_id) + ); + + CREATE TABLE dbix_sequence_release + ( + dataset varchar(50) NOT NULL, + released_id INTEGER NOT NULL, + CONSTRAINT pk_dbi_release PRIMARY KEY (dataset, released_id) + ); + + + /* Each report is characterized by name, date and time. + Monthly reports are automatically assigned 00:00 of the 1st day + in the month. The report contains fields for every service ID + defined across all datasource trees. */ + CREATE TABLE reports + ( + id INTEGER PRIMARY KEY, + rep_date DATE NOT NULL, /* Start date of the report */ + rep_time TIME NOT NULL, /* Start time of the report */ + reportname VARCHAR(64) NOT NULL, /* Report name, such as MonthlyUsage */ + iscomplete INTEGER NOT NULL, /* 0 when the report is in progress, */ + /* 1 when it is ready */ + UNIQUE(rep_date, rep_time, reportname) + ); + CREATE INDEX rep_date_idx ON reports (rep_date); + + + /* Each report contains fields. For each service ID, + the report may contain several fields for various statistics. + Each field contains information about the units of the value it + contains */ + CREATE TABLE reportfields + ( + id INTEGER PRIMARY KEY, + rep_id INTEGER, + name VARCHAR(64) NOT NULL, /* name of the field, such as AVG or MAX */ + serviceid VARCHAR(64) NOT NULL, /* service ID */ + value DOUBLE PRECISION NOT NULL, /* Numeric value */ + units VARCHAR(64) NOT NULL DEFAULT '', /* Units, such as bytes or Mbps */ + UNIQUE (rep_id, name, serviceid) + ); + + +=head2 Devdiscover parameters + +Currently devdiscover allows you to assign service IDs to network interfaces' +input and output traffic counters. Other types of datasources may be +implemented in the future. + +=over 4 + +=item * C<RFC2863_IF_MIB::external-serviceid> + +This discovery parameter specifies which service IDs are assigned to which +interface names. The interface names whould be specified in the form of +their subtree names in Torrus configuration. The example below is +typical for a Cisco IOS router. The value of the parameter consists of +comma-separated strings. The values in each string are separated by colons, +and they correspond to the service ID, interface name, counter type, +and optional destination tree names separated by the pipe symbol (|). +The interface name can be prefixed by hostname and slash (/), +the same way as in C<RFC2863_IF_MIB::tokenset-members>. +All strings are case-sensitive. Three counter types are supported: C<In>, +C<Out>, and C<Both>. When set to C<Both>, the service ID is appended with +C<_IN> or C<_OUT> postfix accordingly, for input and output byte counters. + + <!-- global parameter that will match specific routers --> + <param name="RFC2863_IF_MIB::external-serviceid"> + CUSTOMERONE:nyc01br01/GigabitEthernet9_2_1:Both, + CUSTOMERTWO:wdc01br02/GigabitEthernet6_3_1:Both, + </param> + + <host> + <param name="snmp-host" value="lsn01br01"/> + <!-- host-specfic parameter --> + <param name="RFC2863_IF_MIB::external-serviceid"> + UPSTREAM1_IN:FastEthernet0_0_0:In:upstreams, + UPSTREAM1_OUT:FastEthernet0_0_0:Out:upstreams, + UPSTREAM2:GigabitEthernet0_1_1:Both:upstreams, + CUST1:GigabitEthernet0_2_2:Both:customers|cust1, + </param> + </host> + +=item * C<CiscoIOS_MacAccounting::external-serviceid> + +The same format as for the parameter listed above, but instead of +interface names, you can specify the MAC accounting peer, in one +of the following formats: AS number (I<AS12345>), IP address, or peer's MAC +address (I<0x0003319c4200>). + +=back + + + +=head2 Torrus XML configuration parameters + +You can skip this section if Devdiscover provides all desired functionality. +It explains parameters additional to those described in I<Torrus XML +Configuration Guide>. + +The collector's ExternalStorage module is designed for storing the data to +a generic external storage, and the default external storage is the SQL +database. + +=over 4 + +=item * C<storage-type> + +Mandatory parameter for datasource type C<collector>. Comma-separated list +of storage types. The collected value is duplicated on every storage listed. +Supported values are: C<rrd>, C<ext>. For C<ext> (external storage), +see the I<Reporting Setup Guide>. + +=item * C<ext-dstype> + +Mandatory datasource type to be used in external storage. Accepted +values are: C<GAUGE>, C<COUNTER32>, C<COUNTER64>. + +=item * C<ext-service-id> + +Mandatory service ID for the external storage. + +=item * C<ext-service-units> + +Optional units for the collected value. The only supported value is +C<bytes>. + +=item * C<ext-service-trees> + +(B<New in version 1.0.7>) Optional list of comma-separated tree names. +If specified, the report generator will produce report in corresponding trees. +By default it's the tree which runs the collector process. + +=back + + + +=head2 Enable displaying of the reports in the web interface + +First, enable the reports displaying in <torrus-siteconfig.pl>: + + $Torrus::Renderer::displayReports = 1; + +Second, configure the ACL for your users that are allowed to see the reports +in the web interface: + + torrus acl --modgroup=admin --permit=DisplayReports --for=mytree + +In this example, members of the group C<admin> will be prompted +with the C<[Reports]> shortcut in the web interface's bottom of the page +for a given tree. For easier setup, the tree name may be replaced with +asterisk (*) to allow this option for all trees. + + +=head2 Generate reports + +Report generation is usually a CPU-intensive task. A monthly report calculation +for one service ID may take several dozens of seconds of CPU time. +This uit's recommended to use the C<nice> command to lower the process +priority. + +The C<torrus genreport> (or simply C<torrus report>) command-line utility +is designed for two different tasks: calculation of a single report +for the period chosen, and generation of output HTML for all reports +available. + +The example below generates the monthly usage report for September 2005: + + nice torrus report --report=MonthlyUsage --date=2005-09-01 --debug + +The next example generates HTML output for all reports that are found +in the database: + + nice torrus report --genhtml --tree=customers + +It makes sence to set up a monthly cron job and generate the reports on +the first day of every month, with the command like follows: + + nice torrus report --report=MonthlyUsage \ + --date=`perl -e 'use Date::Format; + print time2str("%Y-%m-%d", time()-1728000)'` + +The HTML output is optimized for printing, and is quite easy +to navigate. The overview page provides the list of years. Clicking to the +year leads you into the list of monthly reports available. +Each monthly report consists of a table for each report name. +For C<MonthlyUsage>, the data is organized in five columns: +the service ID, average monthly rate, 95th percentile of the rates, +maximum rate throughout the month, unavailable samples (how many 5-minutes +intervals are missed in the collected data), and monthly volume (which +is roughly less than the actual volume by the percentage of missed samples). +Also clicking a service ID leads to its monthly report throughout the year. + + +=head2 Getting the sum or maximum value from several service IDs + +A new utility has been sponsored by nexellent ag (www.nexellent.ch), a +managed hosting solution provider near Zurich. + +The utility C<srvderive> can be used to generate a +new service ID which would contain sum or maximum of values of other +service IDs. You would usually run this utlity monthly, just before generating +the monthly reports: + + torrus srvderive --verbose --start=20080801 --month \ + --out=JSMITH_SUM_OUT --func=SUM JSMITH01_OUT JSMITH02_OUT + + torrus srvderive --verbose --start=20080801 --month \ + --out=JSMITH_SUM_IN --func=SUM JSMITH01_IN JSMITH02_IN + + + + + + +Copyright (c) 2005-2008 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> diff --git a/torrus/doc/rpnexpr.pod.in b/torrus/doc/rpnexpr.pod.in new file mode 100644 index 000000000..c85e63677 --- /dev/null +++ b/torrus/doc/rpnexpr.pod.in @@ -0,0 +1,106 @@ +# rpnexpr.pod - Torrus RPN expressions guide +# Copyright (C) 2002 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: rpnexpr.pod.in,v 1.1 2010-12-27 00:04:31 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 RPN expressions in Torrus + +In Torrus framework, RPN expressions are the superset of those +in RRDtool version 1.0. See the C<rrdtool graph> manual at +E<lt>http://oss.oetiker.ch/rrdtool/doc/rrdgraph_rpn.en.htmlE<gt>. + +=head2 New functions added + +=over 4 + +=item * NE + +Pops two arguments from stack, and pushes 0 if the arguments are equal, +and 1 otherwise. + +=item * AND, OR + +These functions pop two arguments from stack, and push back the result of +logical operation. Unlike C operators, + +=item * NOT + +Pops one value from stack and pushes 0 if the argument is nonzero, +otherwise 1. + +=item * ABS + +Pops one value from stack and pushes the absolute value of it. + +=item * NOW + +Pushes the current time, in seconds since Epoch. + +=item * MOD + +Equivalent of C<%>, the modulo operator. In Torrus parameter value, +percent sign is reserved for parameter substitution. + +=item * NUM + +Returns zero if the argument is undefined, and the argument's numeric value +otherwise + +=item * INF, NEGINF + +Returns the positive or negative infinity. + +=back + +=head2 Data access + +In certain context, the values of the datasources can be evaluated +into RPN expression. + +The general format for data access is following: + + {FUNC@PATH(-OFFSET)} + +C<FUNC@> specifies a special function to be performed on the +data being accessed. + +For monitor expressions, C<T@> returns the timestamp of the data source. + +For C<rrd-cdef> leaf types and for C<rrd-multigraph> datasource types, +the following functions affect the graph shape: C<AVERAGE@>, C<MIN@>, +C<MAX@>, and C<LAST@>. They cause the corresponding Consolidation Function +being used when creating a graph. + +C<PATH> specifies the relative name for the data source. +If omitted, the current leaf value is taken. If starts with C</>, +the path is considered as absolute. +Path starting with letter denotes the child of the parent subtree. +Double dot (C<../>) in the beginning of the path is interpreted as +current parent's parent subtree. + +C<(OFFSET)> determines the time reference, as described in C<rrdtool fetch> +manual. In addition, the word C<LAST> refers to the latest data timestamp +available. + +C<(OFFSET)> is currently supported in Monitor expressions only. + +=head1 Author + +Copyright (c) 2002-2004 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> diff --git a/torrus/doc/rrfw_torrus_migration.pod.in b/torrus/doc/rrfw_torrus_migration.pod.in new file mode 100644 index 000000000..f29b6e396 --- /dev/null +++ b/torrus/doc/rrfw_torrus_migration.pod.in @@ -0,0 +1,238 @@ +# webintf.pod - Torrus web interface reference +# Copyright (C) 2002 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: rrfw_torrus_migration.pod.in,v 1.1 2010-12-27 00:04:32 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 RRFW to Torrus migration guide + + + +=head2 Introduction + +Torrus is the new marketing name for RRFW (Round-robin Database Framework), +a robust and flexible software package for data series processing. +The last release of RRFW is 0.1.8. The upcoming release 1.0.0 of Torrus +will introduce some significant changes and design improvements. + +The directory structure of Torrus is more standards-compliant, and more +convenient for system adminisrators. The user files are strictly separated +from the distribution files. The XML configurations and HTML templates +are being searched in multiple directories, thus there will be no longer a +mixture of site-specific files with the ones from distribution. + +In addition, Torrus introduces a commandline wrapper that is installed in +a generic directory for user executables (by default, F</usr/local/bin>). +This greatly simplifies the site administrator's tasks. + +The plugins infrastructure is completely redesigned. +The plugin installation procedure is separated from the main software +installation. In addition, plugin installers set up their initialization +scripts in special directories, so that there's no need for plugin +initialization in F<torrus-siteconfig.pl> and other files. + +Further on, we assume that RRFW is installed in its default directory, +F</usr/local/rrfw-0.1>, and Torrus is installed with default paths. These +paths may differ in your installation. +We refer to TORRUS_DISTR as the unpacked Torrus distribution path. + + + +=head2 Software installation + +Create a new user: C<torrus> and group: C<torrus>. The user ID that is +used by Apache process must be a member of this group. Depending on the +system, this user may be named as C<www>, C<httpd>, C<nobody> etc. Consult +your Apache configuration for details. + +Install Torrus. If your system already runs RRFW release 0.1.8, +all prerequisites should be already in place. Then you simply unpack +the Torrus distribution, and from its directory execute + + ./configure + make install + +If required, download and unpack the Torrus plugins. Then for each plugin, +execute + + torrus install_plugin <UNPACKED_PLUGIN_DIR> + + + +=head2 The Perl configuration files + +Te distribution contains a short Shell script called +C<TORRUS_DISTR/setup_tools/replace_rrfw.sh>. This script takes one file name +as an argument, replaces all occurrences of I<RRFW> to I<Torrus> and I<rrfw> +to I<torrus>, and finally replaces the specified file with the new one. + +Copy the site configuration files from RRFW to Torrus directory: + + cd /usr/local/etc/torrus/ + cp /usr/local/rrfw-0.1/share/rrfw/rrfw-siteconfig.pl \ + conf/torrus-siteconfig.pl + TORRUS_DISTR/setup_tools/replace_rrfw.sh conf/torrus-siteconfig.pl + +If needed, follow the same procedure for F<devdiscover-siteconfig.pl> +and other site configs. + + + +=head2 XML configuration files + +The format of XML fles has not changed, so you simply copy +all locally defined files into F</usr/local/etc/torrus/xmlconfig>. + +The following Shell commands might be of help. They copy all XML files that +do not occur in F</usr/local/torrus/xmlconfig>, the default path for +distribution supplied files: + + cd /usr/local/rrfw-0.1/share/rrfw/xmlconfig/ + + find . -name '*.xml' -exec test ! -f /usr/local/torrus/xmlconfig/'{}' ';' \ + -print | cpio --create --file=/tmp/allxml.cpio + + cd /usr/local/etc/torrus/xmlconfig/ + + cpio --extract --make-directories --preserve-modification-time \ + --file=/tmp/allxml.cpio + +After copying XML files, compile them in Torrus: + + torrus compilexml --all --verbose + + + +=head2 Monitor actions + +If you utilize the monitor daemon, you will most probably need +to change the action statements. + +In the action of type C<exec>, the C<command> parameter should be edited. +RRFW was usually referencing the email notification command as +I<$RRFW_HOME/bin/action_printemail>. In Torrus, this command should be +referred as I<$TORRUS_BIN/action_printemail>. + + + +=head2 SNMP discovery files + + cd /usr/local/etc/torrus/ + cp /usr/local/rrfw-0.1/share/rrfw/discovery/*.ddx discovery/ + +The treatment of C<output-file> parameter has slightly changed. +In RRFW, relative filename meant relative to the current working directory, +and C<$XMLCONFIG> macro was used for referring the default XML files directory. +In Torrus, C<$XMLCONFIG> is still supported, but it is advisory to get rid +of it. Now the relative filenames refer to the user's XML directory, +F</usr/local/torrus/xmlconfig>. Absolute filenames are used as they are. + +In addition, C<torrus devdiscover> acepts the relative input file names, +and searches for them in F</usr/local/torrus/discovery>. + + + +=head2 Web interface ACLs + + cd /usr/local/etc/torrus/ + /usr/local/rrfw-0.1/bin/acledit --export=acl.xml + torrus acledit --import=acl.xml + + + +=head2 Site-specific text templates + +If you used some custom templates (HTML templates for the Web interface, +or text templates for e-mail notifications), copy them to +F</usr/local/etc/torrus/templates>. This directory should contain only +your custom templates. Those delivered with the distribution packages are +located in F</usr/local/torrus/templates>. + + + +=head2 Apache configuration + +Follow the Torrus Web interface guide and configure Apache accordingly. +If needed, use the following Apache command to redirect the users which +use the old URL: + + Redirect /rrfw http://host.domain.com/torrus + +After changing the configuration, stop and start Apache. + + + +=head2 Stop RRFW collector and monitor processes + +Depending on your system configuration, the command would look like + + /etc/init.d/rrfw stop + +Make sure that all old processes are stopped. Then remove the RRFW startup +script from all rc.d directories. + + + +=head2 Change the RRD files ownership + +Depending on your system configuration, the paths for RRD files might be +different. + + chown torrus:torrus /var/snmpcollector/* + + + +=head2 Test and run processes + +For testing purposes, you might want to try launching the collector and +monitor processes, as follows: + + torrus collector --tree=mytree --runonce --debug + +Then copy the Torrus startup script to your system's init directory and setup +new symbolic links, if required. The following example should work for +Sun Solaris: + + cp TORRUS_DISTR/init.d/torrus /etc/init.d + cd /etc/rc3.d + ln -s S90torrus ../init.d/torrus + cd /etc/rc0.d + ln -s K90torrus ../init.d/torrus + +Run the startup script and verify that RRD files get updated. + + + +=head2 Update the cron jobs + +RRFW's cron job F</usr/local/rrfw-0.1/bin/cleanup> should be replaced with +the analogous job from Torrus: F</usr/local/torrus/bin/cleanup> + + + +=head2 Update documentation + +Update your site operational manuals to reflect the new software name, +paths and URLs. + + + +=head1 Author + +Copyright (c) 2004 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> diff --git a/torrus/doc/scalability.pod.in b/torrus/doc/scalability.pod.in new file mode 100644 index 000000000..6bdd51f44 --- /dev/null +++ b/torrus/doc/scalability.pod.in @@ -0,0 +1,274 @@ +# Copyright (C) 2004 Stanislav Sinyagin +# Copyright (C) 2004 Christian Schnidrig +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: scalability.pod.in,v 1.1 2010-12-27 00:04:32 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 Torrus Scalability Guide + +=head2 Introduction + +Installing Torrus in big enterprise or carrier networks requires special +planning and design measures, in order to ensure its reliable and efficient +function. + + +=head2 Hardware Platform Recommendations + +Hardware planning for large Torrus installations is of big importance. +It is vital to understand the potential bottlenecks and performance limits +before purchasing the hardware. + +First of all, you need to estimate the number of devices that you are +going to monitor, with some room for future growth. It is a good practice +first to model the situation on a test server, and then project the +results to a bigger number of network devices. The utilities that +would help you in assessing the requirements are C<torrus configinfo> and +C<torrus schedulerinfo>. + +The resources for planning are the server CPU, RAM, and disks. +While CPU and RAM are of great importance, it is the disk subsystem that +often becomes the bottleneck. + +=head3 CPU + +For large installations, CPU power is one of the critical resources. + +One of CPU-intensive processes is XML configuration compiler. A configuration +for few hundred of nodes may take few dozens of minutes to compile. In some +complicated configuration, it may require few hours to recompile the whole +datasource tree. Here CPU power means literally your time while testing the +configuration changes or troubleshooting a problem. + +The SNMP collector is quite moderate in CPU usage, still when the number of +SNMP variables reaches dozens of thousands, the CPU power becomes +an important resource to pay attention to. In addition, the collector +process initialization time can be quite CPU-intensive. This happens every +time the collector process starts, or when the configuration has been +recompiled. + +The empiric estimation made by Christian Schnidrig is that one SNMP counter +collection every 5 minutes occupies approximately 1.0e-5 of the +Intel Xeon 2.8GHz time, including the OS overhead. For example, +the Torrus collectors running on 60'000 counters would make the server +busy at the average of 60%. + + +=head3 Memory + +The collector would need RAM space to store all the counters information, +and of course it's undesirable to swap. In addition, the more RAM you have +available for disk cache, the faster your collector may update the data files. + +Each update of an RRD file consists of a number of operations: open a file, +read the header, seek to the needed offset, and then write. With enough disk +cache, it is possible that the read operations are made solely from RAM, +and that significantly speeds up the collector running cycle. + +According to Christian Schnidrig's empiric estimations, 30 KB RAM per counter +should be enough to hold all the neccessary data, including the disk cache. +For example, for 60'000 counters this gives 1'757 MB, thus 2 GB of server RAM +should be enough. + +In addition, Apache with mod_perl occupies 20-30 MB RAM per process, so +few hundred extra megabytes of RAM would be good to have. + + +=head3 Disk storage + +It is not recommended to use IDE disks. They are not designed for +continuous and intensive use. As experienced by Christian Schnidrig, +IDE disks don't live long under such load. + +It is recommended to reduce the number of RRD files by grouping +the datasources. This reduces dramatically the number of read and write +operations during the update process. + +As noted by Rodrigo Cunha, reducing the size of read-ahead in the filesystem +may lead to significant optimisation of disk cache usage. RRD update process +reads only a short header in the beginnin of RRD file, and the rest of +readahead data is never reused. On Linux, the following command would +set the readahead size to 4 KB, which equals to i386 page size: + + /sbin/hdparm -a 4 /dev/sda + +For servers with dozens of thousands RRD files, it is recommended to use +hashed data directories. Then the data directories will form a structure of +256 directories, with hash function based on hostnames. See I<Torrus SNMP +Discovery User Guide> for more details. + +Spreading the data files over several physical disks is also a good plus. + + + +=head2 Operating System Tuning + +Depending on the number of trees and processes that run on a single server, +you might require to increase the maximum number of filehandles that +may be opened at the same time, system-wide and per process. +See the manuals for your operating system for more details. + + +=head2 Torrus Configuration Recommendatations + +=head3 BerkeleyDB configuration tuniung + +When using lots of collectors and/or lots of HTTP processes, it is +important to increase the size of BerkeleyDB lock region. +The command + + db_stat -h @dbhome@ -c + +would show you the current number of locks and lockers, and their maximum +quantities during the database history. +The maximum numbers of lock objects and lockers can be tuned by creating the +file F<DB_CONFIG> in the database home directory, F<@dbhome@>. +The following settings would work fine with about 20 collector processes +and 5 HTTP daemon processes: + + set_lk_max_lockers 6000 + set_lk_max_locks 3000 + +It is also recommended to increase the cache size from default 256KB to some +bigger amount. Especially if the database has to hold large Torrus trees +(hundreds or thousands monitored devices). The following line in +F<DB_CONFIG> sets the cache size to 16MB: + + set_cachesize 0 16777216 1 + +After updating F<DB_CONFIG>, stop all Torrus processes, +including HTTP server, then run + + db_recover -h @dbhome@ + +Then start the processes again. Futher info is available at: + +=over 4 + +=item * General access method configuration (BDB Reference) + +http://tinyurl.com/ybymk7t + +=item * DB_CONFIG configuration file (BDB Reference) + +http://tinyurl.com/y9qjodv + +=item * Configuring locking: sizing the system (BDB Reference) + +http://tinyurl.com/ya6dtww + +=item * C API reference + +http://tinyurl.com/yczgnab + +=back + + +=head3 XML compilation time + +For large datasource trees, XML compilation may take dozens of minutes, +if not hours. Other processes are not suspended during the compilation, and +they use the previous configuration version. + +For debugging and testing, it is recommended to create a new tree, +separate from large production trees. That would save you a lot of time and +would allow you to see the result of changes quickly. + + + +=head3 Collector schedule tuning + +The Torrus collector has a very flexible scheduling mechanism. Each data source +has its own pair of scheduler parameters. These parameters are I<period> +and I<timeoffset>. Period is usually set to default 300 seconds. +The time is divided into even intervals. For the default 5-minutes period, +each hour's intervals would start at 00, 05, 10, 15, etc. minutes. +The timeoffset determines the moment within each interval when the data source +should be collected. The default value for timeoffset is 10 seconds. This +means that the collector process would try to collect the values at +00:00:10, 00:05:10, ..., 23:55:10 every day. + +Data sources with the same period and timeoffset values are grouped together. +The SNMP collector works asynchronously, and it tries to send as many SNMP +packets at the same time as possible. Due to the asynchronous architecture, +the collector is able to perform thousands of queries at the same time +with very small delay. Within the same collector process, a large number of +datasources configured with the same schedule is usually not a problem. + +If you configured several datasource trees all with the same period and +timeoffset values, each collector process would start flooding the SNMP +packets to the network at the same time. This may lead to packet loss and +collector timeouts. In addition, all collector processes would try to update +the RRD files concurrently, and this would cause overall performance +degradation. Therefore, it is better to assign different timeoffset values +to different trees. This may be achieved by manually specifying the +C<collector-timeoffset> parameter in discovery configuration files. + +In large installations, the collector schedules need thorough planning and +tuning to insure maximum performance and minimize load on the network devices' +CPUs. The C<torrus schedulerinfo> utility is designed to help you in +this planning. +It shows two types of reports: configuration report gives you the idea +of how many datasources are queried at which moments in time. The runtime +report gives you realtime statistics of collector schedules, including +average and maximum running cycle, and statistics on missed or delayed cycles. + +There is a feature that eases the load in large installations. With +dispersed timeoffsets enabled, the timeoffset for each datasource is +evenly assigned to one of allowed values, based on the name of the host, +and name of the interface. By default, these values are: 0, 30, 60, ..., 270. +With thousands of datasources, this feature smoothens the CPU and disk load +on Torrus server, and avoids CPU usage peaks on network devices with big number +of SNMP variables per device. It is recommended to analyse the current +scheduler statistics before using this feature. If you run several large +datasource trees, don't forget to plan and analyse the schedules for the whole +system, not just for one tree. + + +=head2 Distributed setup + +=head3 NFS-based setup + +The following setup allows you to distribute the load among several +physical servers. + +Several Torrus (backend) servers which run collectors +and store RRD files in the local storage, shared by NFS. +The frontend server runs the Web interface, and probably some monitor +processes, accessing the data files by NFS. + +It is possible to organize the directory structure so that each data file +would be seen at the same path on every server. Then you can keep identical +Torrus configurations on all servers, and launch the collector process only on +one of them. XML configuration files may be shared via NFS too. + +Be aware that BerkeleyDB database home directory cannot be NFS-mounted. +See the following link for more details: +http://www.sleepycat.com/docs/ref/env/remote.html + +Backend servers may run near the limits of their system capacities. +70-80% CPU usage should not be a problem. For the frontend machine, +it is preferred that at least 50% of average CPU time is idle. + + +=head1 Authors + +Copyright (c) 2004-2005 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> + +Copyright (c) 2004 Christian Schnidrig E<lt>christian.schnidrig@bluewin.chE<gt> diff --git a/torrus/doc/snmpdiscovery.pod.in b/torrus/doc/snmpdiscovery.pod.in new file mode 100644 index 000000000..9b23382c7 --- /dev/null +++ b/torrus/doc/snmpdiscovery.pod.in @@ -0,0 +1,1115 @@ +# Copyright (C) 2002-2009 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: snmpdiscovery.pod.in,v 1.1 2010-12-27 00:04:35 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 Torrus SNMP Discovery User Guide + +=head2 Introduction + +In many (but not only) cases Torrus is used for SNMP monitoring. +It provides powerful tools which automate the process of devices' MIB +discovery. + +The discovery tools consist of two programs: C<torrus devdiscover> performs +the SNMP discovery, based on the discovery instructions XML file. +The result of its work is a new Torrus datasource configuration file. +Another utility, C<torrus genddx>, is a program that generates the +basic discovery instructions file based on a set of commandline options. + +The device discovery XML, or as we call them DDX files, are usually +resided in F<@siteconfdir@/discovery/> directory. This is the default +path to search for them when the absolute path is not given. + +=head2 C<torrus genddx>: Discovery instructions generator + + Usage: torrus genddx options... + Options: + --host=hostname router hostname + --hostfile=filename space-separated router hostnames file + --out=outfile output file. [routers.ddx] + --discout=filename discovery output file [routers.xml] + --domain=domain optional DNS domain name + --version=v SNMP version [2c] + --community=string SNMP read community [public] + --port=number SNMP port [161] + --retries=number SNMP retries [2] + --timeout=number SNMP timeout [10] + --subtree=string Subtree name [/Routers] + --datadir=path data-dir parameter [@defrrddir@] + --holtwinters Enable Holt-Winters analysis + +This utility generates C<devdiscover> instructions XML file (DDX) based on +commandline options and a plain list of SNMP agents' hostnames. +Hostnames are specified with one or many C<--host=hostname> options, +or a plain text file with space-separated hostnames. + +Each host may have a symbolic name. This symbolic name is used as +the host-level subtree name. The symbolic name follows the hostname with +a semicolon. + +By default, the devices are placed into C</Routers/> subtree hierarchy. +You may change the subtree name with the I<--subtree> option. +Single slash as subtree name would cause host-level subtrees placed at the top +of the datasources tree. + +By default, C<genddx> specifies the discovery output file as <routers.xml>, +and it would be placed in site XML configuration directory. +You most probably will change this by using the C<--discout> option. + +Examples: + + torrus genddx --out=ch-langenthal.ddx \ + --discout=ch-langenthal.xml \ + --host=192.168.34.35:Langenthal_PE1 \ + --host=192.168.34.36:Langenthal_PE2 \ + --host=192.168.34.37:Langenthal_CE_Stadtverwaltung \ + --community=blahBlah \ + --subtree=/MPLS/CH/Bern/Langenthal + + torrus devdiscover --in=ch-langenthal.ddx + +B<Note:> C<genddx> is designed as a one-time utility. You may run it to create +a typical discovery file with basic set of options. Then the discovery +configuration XML would be the primary source of information, and it should +be maintained by manual editing, or by some other automated means. +Alternatively you may use C<ttproclist> utility and generate highly customized +discovery instruction files based on static templates and lists of SNMP nodes. +See L<torrus_ttproclist(@mansec_usercmd@)> manpage for more details and +examples. + + + +=head2 C<torrus devdiscover>: SNMP discovery tool + + Usage: torrus devdiscover --in=filename.ddx options... [ddx files] + Options: + --in=filename.ddx discovery instructions XML file(s) + --mkdir create data-dir directories + --limit=regexp limit the discovery by output files + --forcebundle always write the bundle file + --fallback=integer maximum age of XML file to fall back to + --threads=integer number of parallel discovery threads + --verbose print extra information + --debug print debugging information + --snmpdebug print SNMP protocol details + +This utility performs the SNMP discovery of devices listed in the input +DDX file. The output XML file is the Torrus datasources configuration. +Output file name is taken from C<output-file> parameter in the DDX. +If the output file is not an absolute path, the file is placed +in the site XML configuration directory (F<@sitexmldir@>). + +C<devdiscover> is accompanied by a number of MIB- or vendor-specific +modules, each responsible for finding specific SNMP variables in +the SNMP device, and for generating a piece of Torrus configuration XML +file responsible for that specific MIB. The list of supported generic MIBs and +vendors is constantly growing. It is quite easy to create new discovery +modules, and the internals are documented in +I<Torrus SNMP Device Discovery Developer's Guide>. + +The output file automatically includes all required prerequisite +generic and vendor template definition files. + +Behaviour of C<devdiscover> is controlled by variables in +F<@siteconfdir@/devdiscover-siteconfig.pl> file. Default values for +those variables reside in F<@cfgdefdir@/devdiscover-config.pl>. + +For large installations, it is recommended to place RRD files into +a hashed directory structure. You can enable this feature by setting + + $Torrus::DevDiscover::hashDataDirEnabled = 1; + +in your F<devdiscover-siteconfig.pl> file. +Then launching C<devdiscover> with C<--mkdir> option would automatically +create the subdirectories inside C<data-dir>. + +The XML files produced by C<devdiscover> may be automatically changed +with some local site-specific scripts. See XUpdate usage example in +I<Torrus User Guide>. + + +=head2 DDX, the discovery instructions file + +The input file for C<devdiscover> is an XML file. Its DTD is available +in Torrus distribution in F<snmp-discovery.dtd>. + +A typical place to store the discovery XML is F<@siteconfdir@/discovery/>. + +Example: + + <?xml version="1.0" encoding="UTF-8"?> + <snmp-discovery> + <file-info> + <format-version> + 1.0 + </format-version> + </file-info> + <creator-info> + Torrus version 0.1.4d + This file was generated by command: + /usr/local/torrus-0.1/bin/genddx \ + --discout=share/torrus/xmlconfig/myrouters.xml \ + --community=blahblah --host=10.0.0.1 --host=10.0.1.1 + On Tue Dec 2 17:43:30 2003 + </creator-info> + <param name="data-dir" value="@defrrddir@"/> + <param name="domain-name" value=""/> + <param name="host-subtree" value="/Routers"/> + <param name="output-file" value="myrouters.xml"/> + <param name="rrd-hwpredict" value="no"/> + <param name="snmp-community" value="blahblah"/> + <param name="snmp-port" value="161"/> + <param name="snmp-retries" value="2"/> + <param name="snmp-timeout" value="10"/> + <param name="snmp-version" value="2c"/> + <host> + <param name="snmp-host" value="10.0.0.1"/> + <param name="symbolic-name" value="10.0.0.1"/> + </host> + <host> + <param name="snmp-host" value="10.0.1.1"/> + <param name="symbolic-name" value="10.0.1.1"/> + </host> + </snmp-discovery> + +=head3 XML elements + +=over 4 + +=item * C<snmp-discovery> + +Mandatory. The top-level element. + +=item * C<file-info> + +Mandatory. It must contain the element C<format-version>. + +=item * C<format-version> + +Mandatory. It must contain a format version currently +supported by devdiscover. Currently supported version is C<1.0>. + +=item * C<creator-info> + +Optional. May contain the information about the file creator: a human author +name, or a program. + +=item * C<param> + +Some parameters are mandatory. This element defines a global or host-specific +parameter. Mandatory attribute C<name> identifies the parameter, +and the value is taken eother from C<value> attribute, or from the +textual content of the element. + +C<param> element should be the child element of C<snmp-discovery> for global +parameters or C<host> for host-level parameters. Host-level parameters +override the values of global parameters. + +These parameters are for C<devdiscover> only. They are not Torrus configuration +parameters, although some of them are directly copied into the generated +configuration file. + +=item * C<host> + +Mandatory. Defines a host to run SNMP discovery. + +=back + + +=head3 Common parameters + +=over 4 + +=item * C<collector-period>, C<collector-timeoffset>, +C<collector-dispersed-timeoffset>, C<collector-timeoffset-min>, +C<collector-timeoffset-max>, C<collector-timeoffset-step>, +C<monitor-period>, C<monitor-timeoffset> + +Optional. When defined, these parameters override those from C<snmp-defaults> +template in F<snmp-defs.xml>. + +=item * C<output-file> + +Mandatory. Specifies the output filename for generated Torrus configuration. +If it's a relative path, the file is placed in F<@sitexmldir@> directory. + +=item * C<output-bundle> + +Optional. Specifies a comma-separated list of XML file names for bundle +output. Each bundle file will contain E<lt>includeE<gt> statement for each +corresponding C<output-file>. + +=item * C<snmp-ipversion>, C<snmp-transport>, C<snmp-port>, + C<snmp-community>, C<snmp-version>, C<snmp-timeout>, + C<snmp-retries>, C<snmp-host>, C<snmp-username>, C<snmp-authkey>, + C<snmp-authpassword>, C<snmp-authprotocol>, C<snmp-privkey>, + C<snmp-privpassword>, C<snmp-privprotocol> + +Mandatory SNMP session parameters. Authentication parameters depend on the +SNMP version used. See the I<XML Configuration Guide> for details. +These parameters define the SNMP agent properties and are +copied one-to-one to the output configuration. + +=item * C<domain-name> + +Optional. Defines a DNS domain name to be appended to C<snmp-host>. + +=item * C<snmp-localaddr> and C<snmp-localport> + +Optional parameters specifying the local socket binding address and port. + +=item * C<data-dir> + +Mandatory. Defines the directory path where RRD files for this host +are stored. In case if hashed directories are enabled, C<data-dir> specifies +the base path under which the hashed subdirectories are created. + +=item * C<symbolic-name> + +Optional. Determines the host-specific subtree name. If not specified, +the subtree is named by C<system-id>, or by C<snmp-host> if system ID is +not defined. + +=item * C<system-id> + +Optional. If defined, it overrides the default value of system ID, which +is equal to the value of C<snmp-host>. + +=item * C<nodeid-device> + +Optional. Defines the host-specific reference for I<nodeid>. Default value +is equal to C<system-id>. + +=item * C<snmp-oids-per-pdu> + +Optional. When defined, these parameters overwrites the value from the +template and vendor-specific discovery modules. + +=item * C<snmp-check-sysuptime> + +Optional. Default: C<yes>. Devdiscover sets this parameter to C<no> when it +finds SNMPv2-MIB::sysUpTime variable unavailable in the device. + +=item * C<snmp-max-msg-size> + +Optional. If defined, it sets the SNMP maximum message size different from +default. The default value is 1470 (defined in Net::SNMP). + +=item * C<host-subtree> + +Optional. Defines the datasourse tree path under which the host-specific +subtree is created. + +=item * C<rrd-hwpredict> + +Optional. Valid values: C<yes>, C<no>. Determines if Holt-Winters forecasting +should be enabled for the given host. + +=item * C<disable-devtypes> + +Optional. Comma-separated list of discovery device types that need to be +excluded from discovery process. For example, ATMEL appliances conflict with +Empire SystemEdge MIBs, and you need to disable C<EmpireSystemedge> module +in order to run the discovery on those appliances. + +=item * C<only-devtypes> + +Optional comma-separated list of device types. If defined, only the specified +types will be used for device probing. + +=item * C<host-aliases> + +Optional comma-separated list of alias paths for a given host. Aliases +must be unique for each host. + +=item * C<custom-host-templates> + +Optional comma-separated list of template names that will be applied +to the resulting XML configuration at the host level. + +=item * C<include-files> + +Optional comma-separated list of XML files that will be listed in C<include> +statements in the resulting XML output. + + +=item * C<host-copy-params> + +Optional comma-separated list of parameter names that should be copied +from the discovery configuration file to the generated Torrus configuration +at the host level. + +=item * C<selectors> + +Optional comma-separated list of object selectors. They are explained in more +detail below. + +=item * C<disable-snmpcollector> + +When set to C<yes>, this parameter disables SNMP collection for this +host. It is useful for creating custom views, in conjunction with +C<RFC2863_IF_MIB::only-interfaces> parameter. + +=item * C<define-tokensets> + +Semicolon-separated (;) list of pairs of tokenset names and descriptions. +Each tokenset name is followed by colon (:) and the description text: + + <param name="define-tokensets"> + important-graphs: Important Graphs; + unimportant-graphs: Unimportant Graphs + </param> + +=item * C<suppress-legend> + +if set to C<yes>, the legend is not shown. It usually has uptime, +software version, and contact information for the SNMP device. + +=item * C<comment> + +Sets the comment string for the host. + +=item * C<show-recursive> + +Default: C<yes>. When set to C<no>, the link to the recursive view at the +host level is omitted. + +=item * C<template-registry-overlays> + +If defined, this should be a comma-separated list of template registry +entries that override the default template references. The overlaying +templates should be referred in +C<%Torrus::DevDiscover::templateOverlays>. +For example, we want to redefine the interface counter template. Then +in the DDX file, we set + + <param name="template-registry-overlays" value="my_ifcounters"/> + +Then in F<devdiscover-siteconfig.pl> we set + + %Torrus::DevDiscover::templateOverlays = { + 'my_ifcounters' => { + 'RFC2863_IF_MIB::iftable-octets' => { + 'name' => 'my-iftable-octets', + 'source' => 'mycustom-rfc2863.if-mib.xml' + }, + 'RFC2863_IF_MIB::ifxtable-hcoctets' => { + 'name' => 'my-ifxtable-hcoctets', + 'source' => 'mycustom-rfc2863.if-mib.xml' + }, + }}; + + +=back + + +=head3 Parameters for C<RFC2863_IF_MIB> + +This discovery module is responsible for agent's interfaces table and +interface counters. Recognized optional parameters are: + +=over 4 + +=item * C<RFC2863_IF_MIB::suppress-hc-counters> + +Some agents do not implement 64-bit counters correctly. When this parameter +is set to C<yes>, 64-bit interface counters are not used for the host. +For Cisco IOS devices, the C<CiscoIOS> discovery module tries to detect +such situation automatically. + +=item * C<RFC2863_IF_MIB::subtree-name> + +Defines the child subtree name within host-level subtree where interface +counters are located. Default: C<Interface_Counters>. + +=item * C<RFC2863_IF_MIB::subtree-comment> + +Defines the comment string for interface counters subtree. +Default: I<Interface traffic and error counters>. + +=item * C<RFC2863_IF_MIB::list-admindown-interfaces> + +If set to C<yes>, interfaces with ifAdminStatus set to other than up(1) +are included in the discovery results. +By default, such interfaces are not listed. + +=item * C<RFC2863_IF_MIB::list-notpresent-interfaces> + +If set to C<yes>, the interfaces with ifOperStatus status set to notPresent(6) +are included in the discovery results. By default, such interfaces are +not listed. + +=item * C<RFC2863_IF_MIB::exclude-down-interfaces> + +If set to C<yes>, the interfaces with ifOperStatus equal to down(2) +are excluded from the discovery results. + +=item * C<RFC2863_IF_MIB::exclude-interfaces> + +Comma-separated list of interface names which should be excluded from +configuration. Spaces are allowed between the names and commas. +The names should be the ones that are used for interface subtrees. + +=item * C<RFC2863_IF_MIB::only-interfaces> + +If defined, this parameter specifies the list of interfaces that will be +included in the discovery results. The names should match the interface +subtree names. Caution: if specified incorrectly, this parameter may +disable discovery for all interfaces on a device. + +=item * C<RFC2863_IF_MIB::tokenset-members> + +This parameter defines which interfaces' C<InOut_bps> leaves to add to +which tokensets. The value is a semicolon-separated (;) list of +entries of form I<tset:interface,interface>, where I<tset> is a name of the +tokenset, and the I<interface> is the subtree name of the corresponding +interface. The token sets must be defined elsewhere in Torrus configuration. +Example: + + <host> + <param name="snmp-host" value="192.168.49.131"/> + <param name="RFC2863_IF_MIB::tokenset-members"> + clusters: 10_1, 10_2; + uplinks: 1_1, 1_2 + </param> + </host> + +Alternatively, this parameter can be defined at the global level, +and then each interface should be pretended by the SNMP host name (the same as +in C<snmp-host> parameter) and slash sign (/): + + <param name="RFC2863_IF_MIB::tokenset-members"> + clusters: RTR01/Ethernet0_0, RTR01/FastEthernet2_1; + </param> + + +=item * C<RFC2863_IF_MIB::copy-params> + +Optional comma-separated list of parameter names that would be copied +to the output Torrus configuration at interface level. +For each parameter I<param>, the value for a particular interface I<intf> +will be taken from parameter C<RFC2863_IF_MIB::I<param>::I<intf>> in +the discovery configuration file. Example: + + <host> + <param name="snmp-host" value="192.168.49.131"/> + <param name="RFC2863_IF_MIB::copy-params" value="intf-error-threshold"/> + <param name="RFC2863_IF_MIB::intf-error-threshold::10_1" value="300"/> + <param name="RFC2863_IF_MIB::intf-error-threshold::2_1" value="900"/> + </host> + +=item * C<RFC2863_IF_MIB::ifindex-map-hint> + +Optional. For a device that doesn't have a corresponding vendor-specific +discovery module, this parameter would advice C<devdiscover> how to build +C<ifTable> index mapping. By default, the interfaces are mapped by +C<ifDescr> variables. For many vendors, this would not give reliable +mapping. Valid values are: C<ifName>, C<ifPhysAddress>, and C<ifIndex>. +The first two suggest the mapping by corresponding SNMP variables, and +the third one should be used for devices with fixed C<ifIndex> layout: in +this case, the C<ifIndex> values are recorded as they are at the moment of +discovery. This option is ignored if the device is supported by a vendor +specific discovery module. + +=item * C<RFC2863_IF_MIB::subtree-name-hint> + +Optional. By default, per-interface subtrees are named after the values of +C<ifDescr> SNMP variables. If this option is set to C<ifName>, this +SNMP variable would be used for subtree naming. This option is ignored if +the device is supported by a vendor specific discovery module. + +=item * C<RFC2863_IF_MIB::nodeid-hint> + +Optional. By default, per-interface I<nodeid> is derived from +C<RFC2863_IF_MIB::ifindex-map-hint>. This parameter can change the +reference table for nodeid. Valid values are: +C<ifDescr>, C<ifName>, C<ifAlias>, C<ifIndex>. + + +=item * C<RFC2863_IF_MIB::noout> + +If set to C<yes>, all the interface statistics are skipped from +the XML configuration output. Still the interface table is examined and +the results may be used by other discovery modules. + +=item * C<RFC2863_IF_MIB::bandwidth-usage> + +If set to C<yes>, the bandwidth usage percentage will be shown for those +interfaces where two parameters are defined (in megabits per second): +C<bandwidth-limit-in> and C<bandwidth-limit-out>. These interface +parameters may be set by C<RFC2863_IF_MIB::bandwidth-limits> discovery +parameter, or by selectors with the action C<Parameters>, or by +setting C<RFC2863_IF_MIB::copy-params>. + +=item * C<RFC2863_IF_MIB::bandwidth-limits> + +Defines the values (in megabits per second) for C<bandwidth-limit-in> and +C<bandwidth-limit-out> interface parameters. Semicolon-separated list +of (I<Inteface name>:I<Input limit>:I<Output limit>) values, for example: + + <host> + <param name="snmp-host" value="10.1.1.5"/> + <param name="symbolic-name" value="bsr2k.example.net"/> + <param name="output-file" value="bsr2k.example.net.xml"/> + <param name="RFC2863_IF_MIB::bandwidth-usage" value="yes" /> + <param name="RFC2863_IF_MIB::bandwidth-limits"> + ethernet0_0:10:10; ethernet0_1:20:20; + </param> + </host> + + +=item * C<RFC2863_IF_MIB::traffic-summaries>, +C<RFC2863_IF_MIB::traffic-XXX-path>, C<RFC2863_IF_MIB::traffic-XXX-comment>, +C<RFC2863_IF_MIB::traffic-XXX-interfaces> + +Defines traffic summary graphs. A summary graph presents a sum of +traffic from several interfaces. The interfaces can belong to different +hosts, but then these hosts should have the same C<output-file> parameter +value. C<RFC2863_IF_MIB::traffic-summaries> defines a list of summary names, +C<RFC2863_IF_MIB::traffic-XXX-path> specifies the full path in the +datasource tree to display the graph, optional +C<RFC2863_IF_MIB::traffic-XXX-comment> defines a descriptive comment +for the graph, and C<RFC2863_IF_MIB::traffic-XXX-interfaces> lists the +interfaces that comprise this sum. The interfaces can be defined at the host +level in the form C<name, name, ...> or at the global level in the form +C<host/intf, host/intf, ...>. Example: + + <param name="RFC2863_IF_MIB::traffic-summaries" value="sum1" /> + <param name="RFC2863_IF_MIB::traffic-sum1-path" value="/Summary/Sum1" /> + <param name="RFC2863_IF_MIB::traffic-sum1-comment" value="Test summary" /> + + <host> + <param name="snmp-host" value="router1.network.net"/> + <param name="RFC2863_IF_MIB::traffic-sum1-interfaces" + value="GigabitEthernet0_2" /> + <param name="output-file" value="TEST/core.xml"/> + </host> + + <host> + <param name="snmp-host" value="router2.network.net"/> + <param name="RFC2863_IF_MIB::traffic-sum1-interfaces" + value="GigabitEthernet1_0" /> + <param name="output-file" value="TEST/core.xml"/> + </host> + + +=back + +=head3 Other generic MIB parameters + +=over 4 + +=item * C<RFC2790_HOST_RESOURCES::sysperf-subtree-name> + +Defines the child subtree name within host-level subtree where system CPU +and memory statistics are located. Default: C<System_Performance>. + +=item * C<RFC2670_DOCS_IF::upstreams-only> + +If set to C<yes>, only the DOCSIS upstream statistics are enabled, and +downstream and MAC layer stats are skipped. + +=back + +=head3 Vendor parameters + +=over 4 + +=item * C<Arbor_E::disable-bundle-offer>, + C<Arbor_E::disable-bundle-offer-deny>, + C<Arbor_E::disable-bundle-offer-pktsize>, + C<Arbor_E::disable-bundle-offer-rate>, + C<Arbor_E::disable-bundle-offer-subcount>, C<Arbor_E::disable-flowdev>, + C<Arbor_E::enable-bundle-name-rrd>, + C<Arbor_E::disable-e30-buffers>, C<Arbor_E::disable-e30-bundle>, + C<Arbor_E::disable-e30-cpu>, + C<Arbor_E::disable-e30-fwdTable>, + C<Arbor_E::disable-e30-fwdTable-login>, + C<Arbor_E::disable-e30-hdd>, C<Arbor_E::enable-e30-hdd-errors>, + C<Arbor_E::disable-e30-hdd-logs>, C<Arbor_E::disable-e30-l2tp>, + C<Arbor_E::disable-e30-mem>, C<Arbor_E::enable-e30-mempool>, + C<Arbor_E::disable-e30-bundle>, C<Arbor_E::disable-e30-bundle-deny>, + C<Arbor_E::disable-e30-bundle-rate>, C<Arbor_E::disable-e30-slowpath> + +When set to C<yes>, the corresponding statistics are included or excluded from +the graphs. + +=item * C<Arbor_E::enable-e30-bundle-name-rrd> + +When set to C<yes>, the data will be written to filenames based on the name +bundle instead of by the ID of the bundle. + +=item * C<Apple_AE::disable-clients-stats> + +When set to C<yes>, wireless client machines are not tracked. + +=item * C<CiscoGeneric::disable-cpu-stats> + +When set to C<yes>, Cisco CPU usage statistics are excluded from discovery. + +=item * C<CiscoGeneric::disable-memory-pools> + +When set to C<yes>, Cisco memory pool usage statistics are excluded from +discovery. For Cisco series 7500, see the note in the +I<Torrus Vendor Support List>. + +=item * C<CiscoGeneric::disable-sensors> + +When set to C<yes>, Cisco temperature sensors are excluded from discovery. + +=item * C<CiscoGeneric::use-fahrenheit> + +When set to C<yes>, Cisco temperature sensors are recorded and displayed +in degrees Fahrenheit. + +=item * C<CiscoGeneric::file-per-sensor> + +When set to C<yes>, Cisco temperature sensor values are stored in +a separate RRD file per sensor ID. This is useful for modular big routers +like Cisco GSR. + +=item * C<CiscoGeneric::disable-psupplies> + +if set to C<yes>, Cisco power supply statistics are not collected. + +=item * C<CiscoGeneric::power-monitor> + +Name of the power supply monitor for Cisco devices. + +=item * C<CiscoIOS::enable-membuf-stats> + +When set to C<yes>, Cisco memory buffer statistics are included to the +discovery. Many IOS releases report faulty information, thus these +stats are disabled by default. + +=item * C<CiscoIOS::disable-ipsec-stats> + +When set to C<yes>, IPSec statistics are excluded from discovery. + +=item * C<CiscoIOS::disable-bgp-stats> + +If set to C<yes>, BGP statistics are not included. + +=item * C<CiscoIOS::enable-vlan-interfaces> + +When set to C<yes>, the interfaces VlanXXX are added to statistics. +By default they are not included, because some hardware platforms give +irrelevant counter statistics. + +=item * C<CiscoIOS::enable-unrouted-vlan-interfaces> + +When set to C<yes>, the interfaces "unrouted Vlan XXX" are added to statistics. +By default they are not included, because some hardware platforms provide +no statistics for such interfaces. + + +=item * C<CiscoCatOS::suppress-noname-ports> + +When set to C<yes>, only those Catalyst ports are included in configuration +which have a port name (set up by C<set port name> command). + +=item * C<CiscoIOS_MacAccounting::bgponly> + +When set to C<yes>, Cisco MAC accounting statistics will be enabled for +those MACs which correspond to BGP peers only. + +=item * C<bgp-as-description-NNNN> + +Specifies a description for an autonomous system number. Currently it's used +with Cisco MAC accounting and Cisco BGP statistics only. + +=item * C<peer-ipaddr-description-AAA_AAA_AAA_AAA> + +Specifies a description for a peer by its IP address. Dots in IP address should +be replaced with underscores. Currently it's used with Cisco +MAC accounting and Cisco BGP statistics only. + +=item * C<CiscoIOS_MacAccounting::tokenset-members> + +Works the same way as C<RFC2863_IF_MIB::tokenset-members> and assigns MAC +accounting peers to tokensets. + +=item * C<CiscoIOS::disable-car-stats> + +When set to C<yes>, the Committed Access Rate statistics are disabled +from discovery. + +=item * C<CiscoIOS::disable-vpdn-stats> + +When set to C<yes>, the VPDN (Virtual Private Dial-up Network) statistics +are disabled from discovery. + +=item * C<CiscoIOS::short-device-comment> + +If set to C<yes>, the Hw Serial and Revision strings are not shown in +device comment. + +=item * C<CiscoSCE::disable-disk>, C<CiscoSCE::disable-gc>, + C<CiscoSCE::disable-qos>, C<CiscoSCE::disable-rdr>, + C<CiscoSCE::disable-subs>, C<CiscoSCE::disable-tp> + +If set to C<yes>, the corresponding statistics are excluded from Cisco SCE +graphs. + +=item * C<FTOS::disable-cpu>, C<FTOS::disable-power>, + C<FTOS::disable-temperature> + +When set to C<yes>, disables the corresponding statistics category. + +=item * C<FTOS::use-fahrenheit>, C<FTOS::file-per-sensor> + +When set to C<yes>, enables the user of fahrenheit temperature, or writes +multiple rrd files. + +=item * C<JunOS::disable-cos>, C<JunOS::disable-cos-red>, + C<JunOS::disable-cos-tail>, C<JunOS::disable-firewall>, + C<JunOS::disable-operating>, C<JunOS::disable-rpf> + +When set to C<yes>, disables the corresponding statistics category for JunOS +devices. + +=item * C<Liebert::disable-temperature>, C<Liebert::disable-humidity>, + C<Liebert::disable-state>, C<Liebert::disable-stats> + +When set to C<yes>, disable the corresponding statistics category for Liebert +devices. + +=item * C<Liebert::use-fahrenheit> + +When set to C<yes>, the temperature readings will be in fahrenheit. + + +=item * C<NetBotz::temp-max>, C<NetBotz::humi-max>, C<NetBotz::dew-max> + +Set a numeric value for the maximum temperature, humidity, or dew point +on NetBotz sensor graphs. The maximum is displayed with a dark red line. + +=item * C<Paradyne::slot-name> + +Mandatory for Paradyne DSLAM devices. It should uniquely identify +the slot within the device. Any sequence of word characters is allowed. + +=back + +See also: I<Torrus Vendor Support List> for the list of supported MIBs and +vendors. + +=head2 Object selectors + +Selectors are a common mechanism for applying customizations to +some discovery objects. For example, you may want to apply a monitor +to byte counters of interfaces that have a special word in the description. +Or apply Holt-Winters prediction to a certain subset of interfaces. + +Selectors are defined in a DDX file as regular parameters. +The parameter C<selectors> defines a list of selector names. +Each selector is identifed by its name and type. The type of selector +defines which objects will be searched: IF-MIB interfaces, or Cisco +temperature sensors, or something else. The parameters are described +below. + +=over 4 + +=item * C<selectors> + +Comma-separated list of selector names. Further below we use C<S> as +selector name, C<A> as attribute name, and C<T> as action name. + +=item * C<S-selector-type> + +Type of objects to be selected. Supported values are: C<RFC2863_IF_MIB>, +C<CiscoCPU>, C<CiscoSensor>. + +=item * C<S-selector-expr> + +An RPN (reverse Polish notation) expression that defines the +object attributes to be checked and relation between them. Attribute names +should be specified in curly braces ({}). The rest of the syntax is described +in I<RPN expressions in Torrus> guide. The attribute names are specific to the +selector type and are described below. + +=item * C<S-A> + +For a given selector name C<S> and attribute name C<A>, +this parameter defines the attribute value that should be compared +to the object's properties. In most cases it defines a regular +expression that should match the value of a corresponding object's +property. + +=item * C<S-selector-actions> + +For a given selector name C<S>, this parameter defines a comma-separated +list of actions to be applied for objects where C<S-selector-expr> returns +true. The action names are specific to the selector type and are +described below. + +=item * C<S-T-arg> + +For a given selector C<S> and action C<T>, this parameter defines +an argument that should be passed to the action. Each action +defines its own meaning of the argument. + +=back + + + +=head3 RFC2863_IF_MIB selector + +This type of selector selects the network interfaces on a SNMP device. +The following attribute names are supported: + +=over 4 + +=item * C<ifSubtreeName>, C<ifSubtreeName1>, ... + +Interface-level subtree name as you see it in the discovery results. +You can compose a complex expression of subtree matches, by +createing attributes with different numbers at the end. + +=item * C<ifComment> + +Comment string that is defined in C<comment> parameter. It is +usually derived from an interface description. + +=item * C<ifType> + +Numeric IANA interface type, as returned by C<ifType> SNMP variable. + +=back + +C<ifType> is compared numerically. +C<ifSubtreeName> and C<ifComment> are regular expressions. +C<ifSubtreeName> accepts multiple expressions separated by space, +and the selector matches if any of these expressions matches the subtree name. + + + +The following actions are supported: + +=over 4 + +=item * C<InBytesMonitor>, C<OutBytesMonitor> + +The argument defines the monitor name to be applied to the input +or output bytes counter. + +=item * C<InDiscardsMonitor>, C<OutDiscardsMonitor>, +C<InErrorsMonitor>, C<OutErrorsMonitor> + +The argument defines the monitor name to be applied to discard and error +counters that are discovered for a given interface. + +=item * C<NotifyPolicy> + +The argument defines the value for C<notify-policy> parameter. See the manual +for F<action_notify> for more details. + +=item * C<HoltWinters> + +No argument needed. This action enables Holt-Winters prediction +for given interface's counters. + +=item * C<NoPacketCounters>, C<NoDiscardCounters>, C<NoErrorCounters> + +No argument needed. The action disables the packet, discard or error counters +for a given interface to be collected. + +=item * C<TokensetMember> + +The argument is a comma-separated list of tokenset names where C<InOutBbs> +graphs would be added. This action complements +C<RFC2863_IF_MIB::tokenset-members>. + +=item * C<Parameters> + +The argument defines additional configuration parameters to be +placed at the interface level. The value should be one +or several C<param=value> pairs separated by semicolon (;). +Parameters defined in C<RFC2863_IF_MIB::copy-params> may override +the ones defined in this action. + +=item * C<InBytesParameters>, C<OutBytesParameters> + +Analagous to C<Parameters>, but the parameters are applied to InBytes and +OutBytes leaves of the selected interface. + +=item * C<DocsisUpSNRMonitor> + +For a DOCSIS CMTS, this action assigns a new monitor to the upstream +Signal/Noise ratio gauge, instead of the default monitor. + +=item * C<DocsisUpSNRTokenset> + +For a DOCSIS CMTS, this action adds the Signal/Noise ratio graph to a +specified tokenset. + +=item * C<DocsisUpFECCorMonitor> + +For a DOCSIS CMTS, this action assigns a monitor to the C<Correctable> +counter of the upstream FEC statistics. + +=item * C<DocsisUpFECUncorMonitor> + +For a DOCSIS CMTS, this action assigns a monitor to the C<Uncorrectable> +counter of the upstream FEC statistics. + +=item * C<DocsisDownUtilMonitor> + +For a DOCSIS CMTS, this action assigns a monitor to the downstream +C<UsedBytes> counter. + +=item * C<DocsisMacModemsMonitor> + +For Cisco uBR, this action assigns a monitor to the C<Modems_Registered> gauge +in the MAC layer stats. + +=item * C<DocsisUpUtilMonitor>, C<DocsisUpSlotsMonitor> + +For Cisco uBR, this action assigns a monitor to upstream utilization and +free contention timeslots gauges correspondingly. + +=back + + +=head3 CiscoCPU selector + +A selector of this type selects CPU statistics Cisco router or +switch. + +The attributes supported are: C<CPUName> and C<CPUDescr>, and their +values are regular expressions that should match the CPU name or description, +as discovered by C<devdiscover>. + +The action supported is C<TokensetMember>, and its argument specifies +the tokenset where to place the CPU statistics graph. + + +=head3 CiscoSensor selector + +A selector of this type selects temperature sensors on a Cisco router or +switch. + +The only attribute supported is C<SensorDescr>, and its value is a regular +expression that should match the sensor description, as discovered +by C<devdiscover>. + +Actions supported: C<Monitor>, C<TokensetMember>. + + +=head3 ALU_SAP selector + +This selector type is designed for SAP entries in Alcatel-Lucent ESS and SR +routers. + +Attributes supported: C<sapDescr> (regexp), C<custDescr> (regexp), +C<sapName> (exact match), C<sapPort> (exact match). + +Actions supported: C<RemoveSAP> (excludes a selected SAP from the datasources). + + + +=head3 Examples + +The following example applies a monitor called C<temp60degrees> to all +inlet sensors on a Cisco device: + + <host> + <param name="snmp-host" value="router1"/> + <param name="output-file" value="router1.xml"/> + <param name="selectors" value="inlet"/> + <param name="inlet-selector-type" value="CiscoSensor"/> + <param name="inlet-selector-expr" value="{SensorDescr}"/> + <param name="inlet-SensorDescr" value="Inlet"/> + <param name="inlet-selector-actions" value="Monitor"/> + <param name="inlet-Monitor-arg" value="temp60degrees"/> + </host> + +The following example enables Holt-Winters prediction and specifies some +parameters to all FastEthernet interfaces which have the string "SRV-ID" +in their descriptions: + + <host> + <param name="snmp-host" value="router2"/> + + <param name="selectors" value="FastEthHW"/> + <param name="FastEthHW-selector-type" value="RFC2863_IF_MIB"/> + + <param name="FastEthHW-selector-expr" + value="{ifSubtreeName},{ifComment},AND"/> + <param name="FastEthHW-ifSubtreeName" value="^FastEthernet"/> + <param name="FastEthHW-ifComment" value="SRV-ID"/> + + <param name="FastEthHW-selector-actions" + value="HoltWinters,Parameters"/> + + <param name="FastEthHW-Parameters-arg" + value="rrd-create-hw-alpha=0.2; rrd-create-hw-beta=0.01"/> + </host> + +The following example sets up the monitors defined in +F<examples/docsis-monitors.xml>: + + <param name="selectors" value="docs"/> + <param name="docs-selector-type" value="RFC2863_IF_MIB"/> + <param name="docs-selector-expr" value="{ifSubtreeName}"/> + <param name="docs-ifSubtreeName" value="^Cable"/> + <param name="docs-selector-actions"> + DocsisUpSNRMonitor, + DocsisUpFECCorMonitor, + DocsisUpFECUncorMonitor, + DocsisDownUtilMonitor, + DocsisMacModemsMonitor, + DocsisUpUtilMonitor, + DocsisUpSlotsMonitor, + InErrorsMonitor, + OutErrorsMonitor + </param> + <param name="docs-DocsisUpSNRMonitor-arg" + value="docsis-snr-1,docsis-snr-2,docsis-snr-3"/> + + <param name="docs-DocsisUpFECCorMonitor-arg" + value="docsis-feccor-1,docsis-feccor-2"/> + + <param name="docs-DocsisUpFECUncorMonitor-arg" + value="docsis-fecuncor-1,docsis-fecuncor-2,docsis-fecuncor-3"/> + + <param name="docs-DocsisDownUtilMonitor-arg" + value="docsis-downutl-1,docsis-downutl-2,docsis-downutl-3"/> + + <param name="docs-DocsisMacModemsMonitor-arg" + value="docsis-modems-1,docsis-modems-2"/> + + <param name="docs-DocsisUpUtilMonitor-arg" + value="docsis-uputil-1,docsis-uputil-2,docsis-uputil-3"/> + + <param name="docs-DocsisUpSlotsMonitor-arg" + value="docsis-upslots-1,docsis-upslots-2,docsis-upslots-3"/> + + <param name="docs-InErrorsMonitor-arg" + value="docs-inerrors-1,docs-inerrors-2"/> + + <param name="docs-OutErrorsMonitor-arg" + value="docs-outerrors-1,docs-outerrors-2"/> + + + +=head1 Author + +Copyright (c) 2002-2005 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> diff --git a/torrus/doc/stylingprofile.pod.in b/torrus/doc/stylingprofile.pod.in new file mode 100644 index 000000000..b785330ed --- /dev/null +++ b/torrus/doc/stylingprofile.pod.in @@ -0,0 +1,217 @@ +# stylingprofile.pod - Guide to Styling Profiles +# Copyright (C) 2003 Shawn Ferry +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: stylingprofile.pod.in,v 1.1 2010-12-27 00:04:32 ivan Exp $ +# Shawn Ferry <sferry at sevenspace dot com> <lalartu at obscure dot org> +# + +=head1 Torrus Styling Profile Guide + +=head2 Styling Profiles + +Styling profiles allow for symbolic names to be used in place of hard +coded values for C<line-color> and C<line-style>. + +=head3 Schema Definitions + +The following styles are defined in the default schema. + +=over 3 + +=item * Required Styles (C<line-style>, C<line-color>) + + + SingleGraph HWBoundary HWFailure + HruleMin HruleNormal HruleMax + BpsIn BpsOut + + +=item * Generic Symbolic styles (C<line-color> only) + + in out + +=item * Symbolic, Symbolic names, for default use in graphs that have up +to ten items (C<line-color> only) + + one two three + four five six + seven eight nine + ten + +=item * Symbolic names for combinatorial graphing (C<line-style>, +C<line-color>) + + red1 red2 red3 + red4 green1 green2 + green3 green4 blue1 + blue2 blue3 blue4 + +=item * Color definitions from the TT2 rgb example set (C<line-color> only) + +Defined in F<@supdir@/styling/colornames.pl> + + black grey25 grey50 + grey75 white red + red25 red50 red75 + green green25 green50 + green75 blue blue25 + blue50 blue75 blood + scarlet rose orange + leaf bud mint + marine sky mauve + lilac + +=item * Color definitions for web html colors (C<line-color> only) + +Defined in F<@supdir@/styling/colornames.pl> + + aliceblue antiquewhite aqua + aquamarine azure beige + bisque blanchedalmond blueviolet + brown burlywood cadetblue + chartreuse chocolate coral + cornflowerblue cornsilk crimson + cyan darkblue darkcyan + darkgoldenrod darkgray darkgreen + darkkhaki darkmagenta darkolivegreen + darkorange darkorchid darkred + darksalmon darkseagreen darkslateblue + darkslategray darkturquoise darkviolet + deeppink deepskyblue dimgray + dodgerblue firebrick floralwhite + forestgreen fuchsia gainsboro + ghostwhite gold goldenrod + gray greenyellow honeydew + hotpink indianred indigo + ivory khaki lavender + lavenderblush lawngreen lemonchiffon + lightblue lightcoral lightcyan + lightgoldenrodyellow lightgreen lightgrey + lightpink lightsalmon lightseagreen + lightskyblue lightslategray lightsteelblue + lightyellow lime limegreen + magenta maroon mediumaquamarine + mediumblue mediumorchid mediumpurple + mediumseagreen mediumslateblue mediumspringgreen + mediumturquoise mediumvioletred midnightblue + mintcream mistyrose moccasin + navajowhite navy oldlace + olive olivedrab orangered + orchid palegoldenrod palegreen + paleturquoise palevioletred papayawhip + peachpuff peru pink + plum powderblue purple + rosybrown royalblue saddlebrown + salmon sandybrown seagreen + seashell sienna silver + skyblue slateblue slategray + snow springgreen steelblue + tan teal thistle + tomato turquoise violet + wheat whitesmoke yellow + +=back + +=head3 Schema Overlay + +I<WARNING: Some styles are mandatory> + +Schema overlays allow the user to extend or override the styles defined in the +default schema. The schema overlays are formatted in the form of a hash of +hashes. + + +=over 4 + +=item * Extending the schema: + +To add the styles, C<##onefish>, C<##twofish>, C<##redfish>, C<##bluefish> +the following entries should be created in a descriptive file located +in the C<styling> directory. + +C<fish-schema.pl> + + $Torrus::Renderer::graphStyles{'onefish'}{'color'} = '##darkred'; + $Torrus::Renderer::graphStyles{'onefish'}{'line'} = 'LINE1'; + + $Torrus::Renderer::graphStyles{'twofish'}{'color'} = '##red'; + $Torrus::Renderer::graphStyles{'twofish'}{'line'} = 'LINE2'; + + $Torrus::Renderer::graphStyles{'redfish'}{'color'} = '##yellow'; + + $Torrus::Renderer::graphStyles{'bluefish'}{'color'} = '##deeppink'; + +Other methods of adding to the hash of hashes are also acceptable. + +=item * Overriding Styles: + +To override specific styles in the existing schema, C<##in>, C<##out>, +entries similar to the following should be created in a Perl file, +preferably located in the local configuration directory. + +C<in_out-override-schema.pl> + + $Torrus::Renderer::graphStyles{'in'}{'color'} = '##yellow'; + $Torrus::Renderer::graphStyles{'out'}{'color'} = '##maroon'; + +Other methods of adding to the hash of hashes are also acceptable. + +=item * Applying your Overlay + +=over 4 + +=item 1. + +In the torrus-siteconfig.pl file, add the variable + +$Torrus::Renderer::stylingProfileOverlay = + $Torrus::Global::cfgSiteDir . '/in_out-override-schema.pl'; + +=item 2. + +Restart apache + +=back + +You may have to wait for the image cache to clear before the changes +take effect. + +=back + +=head3 Schema Replacement + +To replace a schema, create a new schema using torrus-schema.pl as a guide. +Remember some styles are mandatory. + +=over 4 + +=item * Applying your Schema + +In the F<torrus-siteconfig.pl> file, add the variable + + $Torrus::Renderer::stylingProfile = "Your-schema"; + +=item 2. Restart apache + +=back + +You may have to wait for the image cache to clear before the changes +take effect. + +=head1 Author + +Copyright (c) 2003 Shawn Ferry diff --git a/torrus/doc/userguide.pod.in b/torrus/doc/userguide.pod.in new file mode 100644 index 000000000..1e170c937 --- /dev/null +++ b/torrus/doc/userguide.pod.in @@ -0,0 +1,869 @@ +# userguide.pod - Torrus user guide +# Copyright (C) 2003 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: userguide.pod.in,v 1.1 2010-12-27 00:04:32 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 Torrus User Guide + + +=head2 Quick start guide + +The steps below will explain you how to make the thing running. + +B<Install Torrus>. Follow the I<Torrus Installation Instructions> document, +all prerequisits and necessary steps are described there. + +B<What is where>. The executables reside in +F<@pkgbindir@/>. You normally don't need to access this +directory, because the commandline wrapper, C<torrus>, is installed +in a usual execution path (F<@bindir@>). +All site-specific behaviour is controlled by +configuration files in F<@siteconfdir@/>. +Usually you need to change F<torrus-siteconfig.pl> only. In this file, you +must list your XML configuration sources. The datasource trees configuration +is read out of XML files. They are searched in several directories, +normally F<@distxmldir@/> and F<@sitexmldir@/>. The first one contains +files that come with Torrus distribution, and the second one is for your local +site-specific XML files. Global site-specific XML configuration parameters +may be defined in F<site-global.xml>. +XML configuration is compiled into internal database representation +by C<torrus compilexml> command. The database itself is resided in +F<@dbhome@/>, and must be writable by your Apache server +(normally the installer takes care of it). It is safe to re-compile the +configuration while the Torrus daemons are running. + +B<The datasource trees>. Torrus configuration consists of a number of I<trees>. +Each tree is independent from the others. A tree may run one Collector and +one Monitor process. Also the web interface access control lists +differentiate the user rights by datasource trees. + +B<Inside the tree>. A tree defines the hierarchy of Torrus datasources. +The structure of the tree is solely defined by XML configuration files. +The tree consists of I<nodes>, each being either a I<subtree> or a I<leaf>. +Subtrees contain child subtrees and/or leaves. The leaf represents a +datasource: normally this is a numerical value that changes over time. +The leaf is the entity that may be presented as a graph. +There are leaves of special type: I<multigraph>. +They are not numerical values, and are designed for +drawing several values in one graph. Each node has I<path>, a +string that consists of slashes and node names, and uniquely identifies this +node. The path of a subtree always ends with slash, and the root of the tree +has the path consisting of a single slash. + +B<Trees configuration>. The trees are defined in F<torrus-siteconfig.pl>. +See I<Torrus Installation Instructions> for a basic example of tree +configuration. + +B<Round-robin databases>. Currently only one type of data storage is +supported: Round-robin database (RRD) files. See I<RRDtool> manuals +for more details. Each leaf represents a datasource stored in an +RRD file. Of course, several leaves may refer to different datasources within +the same RRD file. Even more, more than one leaf may refer to the same +datasource within an RRD file. RRD files are created and updated either by +C<collector>, or by some other external programs. + +B<Define the targets>. If you only want to collect SNMP counters +from some network devices' interfaces, there's a couple of tools +called C<torrus genddx> and C<torrus devdisover>. +The first one creates a basic discovery instructions file, and the second +one uses the discovery instructions to explore the SNMP device capabilities +and information: interface names, input/output counters, +CPU and memory usage, temperature sensors (for Cisco devices), and many +other vendor-specific statistics sources. + +Torrus is much more than just an SNMP collector. So, when you decide +to use it in a more advanced way, you will have to read the whole bit of +this guide, and also I<Torrus XML Configuration Guide> and probably some +other documents too. + +B<Build the hierarchy>. By default, C<torrus genddx> will put all your +devices into one hierarchy: C</Routers/E<lt>hostnameE<gt>/...>. +The subtree name, C<Routers>, may be changed with a command line option +of C<torrus genddx>. This program may also read the device names +(or IP addresses in case if you don't use DNS) from space-delimited text files. + + torrus genddx \ + --hostfile=myrouters.txt \ + --domain=example.net \ + --community=MySecretSNMPCommunity \ + --out=myrouters.ddx \ + --discout=myrouters.xml \ + --subtree=/My_Routers \ + --datadir=/data1/torrus/collector_rrd + + torrus genddx \ + --hostfile=myswitches.txt \ + --domain=example.net \ + --community=MySecretSNMPCommunity \ + --out=myswitches.ddx \ + --discout=myswitches.xml \ + --subtree=/My_Switches \ + --datadir=/data1/torrus/collector_rrd + + torrus devdiscover --in=myrouters.ddx + + torrus devdiscover --in=myswitches.ddx + +In the example above, the routers' and switches' names are read from +F<myrouters.txt> and F<myswitches.txt> in the user's current directory. +They form a hierarchy with two subtrees: C</My_Routers/> and C</My_Switches/>. +C<genddx> creates the discovery instruction XML files into +F<myrouters.ddx> and F<myswitches.ddx> accordingly. By default, +you would find them in F<@sitedir@/discovery/>. +The result of C<devdiscover> is the Torrus configuration files: +F<myrouters.xml> and F<myswitches.xml>, placed into +F<@sitexmldir@/>. The C<collector> will place the +RRD files into F</data1/torrus/collector_rrd>. Make sure that this directory +exists, has enough free space, and is writable by C<torrus> user. + +B<Note:> the C<genddx> utility is designed as a one-time helper, so +that you create your basic discovery instructions files from scratch. +Further on, the discovery files should be maintained separately. + +Another useful utility is called C<ttproclist>. It can be used to generate +a DDX file from a template and a list of SNMP hosts. It is very useful if +you want to monitor many devices of similar type or function. + +You can also define a I<bundle> file in your DDX file. C<Genddx> will +create it after all devices would discovered, and it will contain +E<lt>includeE<gt> statements for all XML files. This makes it practical to +use one XML file per SNMP host, and use the bundle file for inclusion +in the tree configuration. + +B<Add your XML files to the tree configuration>. For each tree, +F<@siteconfdir@/torrus-siteconfig.pl> lists the XML files that have to be +compiled for it. In the example above, you would add F<myrouters.xml> and +F<myswitches.xml> into C<xmlfiles> array in the tree configuration. + +See I<Torrus SNMP Discovery User Guide> for more details on how +C<genddx> and C<devdisover> interact and how you can customize +the discovery process. + +B<Tip>: in most cases, your hierarchy division will be different. +It might be arranged by geographical locations, or by customer names. +There is a configuration statement that allows you to include other +XML files into configuration, thus giving you a big flexibility +in building the data hierarchies. + +B<Compile the configuration>. After the XML configuration is prepared, +you need to execute the compiler: + + torrus compile --tree=treename --verbose + +For most of the processes that you run within Torrus, you need to specify +the tree name with C<--tree> option. Some proramms accept C<--all> option, +which causes them to process all existing trees. +With C<--verbose> option, the compiler tells you about the files being +processed, and about some other actions that may take quite a long time. +It will also tell you if there's any error in your configuration. + +B<Build the search database>. The search database is updated by executing +the following command: + + torrus bs --global --verbose + +For users that are allowed to display all the trees, you can enable the +global search across all trees: + + torrus acledit --addgroup=staff --permit=GlobalSearch --for='*' + +B<Launch the collector>. Assuming that compilation went smoothly, +you may now launch the data collector: + + torrus collector --tree=treename + +Without additional options, the collector will fork as a daemon +process, and write only error messages in its log file, +F<@logdir@/collector.treename.log>. + +There is a file that is created by C<./configure>, called F<init.d/torrus>. +You may place it into a directory where your system looks for startup scripts +(F</etc/init.d/> on Solaris and some Linuxes, F</usr/local/etc/rc.d/> +on FreeBSD). Probably you need to rename and edit the script before using. +Note that it also executes another daemon, C<monitor>. + +The C<monitor> daemon is used for monitoring the thresholds in the +data files. For more details, see the I<Torrus XML configuration guide>, +in the section about monitor definitions. + +B<Define the ACLs>. By default, user authentication is enabled in the web +interface. You can change this by setting +C<$Torrus::CGI::authorizeUsers = 0> in your F<torrus-siteconfig.pl>. +In order to get use of user authentication, you need to create I<groups> +and I<user> accounts. Each user belongs to one or more groups, and each group +has access to a set of datasource trees. See +I<Torrus Installation Instructions> for a basic example. + +B<Browse with your browser>. Provided that you followed the +installation guide to the end, and your HTTP server is running, +your Torrus hierarchy must be visible with your favorite web browser. + + +=head2 Configuration guidelines + +In complete detail, the XML configuration is described in +I<Torrus XML Configuration Guide>. The guidelines below will help +you to read that document. + +B<Tree structure>. The tree structure is defined by the structure of +C<E<lt>subtreeE<gt>> and C<E<lt>leafE<gt>> XML elements. The rule is simple: +child XML elements of a C<E<lt>subtreeE<gt>> element define the child +nodes in the configuration tree. + +B<Parameters>. Each node has a number of parameters. They are defined +by C<E<lt>paramE<gt>> XML element. Parameters are inherited: +the child node has all its parent's parameters, some of which may be +overridden. + +B<Additive configuration>. The whole XML configuration is additive. +It means that you may define your subtree several times across +your XML configuration, and the new parameters and child nodes will +be added to previously defined ones. + +B<Templates>. Some pieces of configuration may be written as templates, +and then re-used in multiple places. + +The C<configsnapshot> utility generates one large XML file back from +the compiled configuration. Its main purpose is backup of the configuration, +but it can also be used for studying the relationships between templates +and input files. + +=head2 Handling SNMP errors + +During SNMP discovery process, some SNMP devices may not be reachable. +By default, C<devdiscover> reports the error, and does not write the output +XML file containing that device. It also skips writing the bundle files that +contain the output file affected. + +When C<devdiscover> is executed with C<--forcebundle> option, the bundle +files are written, and the output files related to the unreachable +devices are skipped from the bundles. This ensures that we always get +a configuration that may compile and run the collector. + +Another option, C<--fallback=DAYS>, if given together with C<--forcebundle>, +tells the discovery engine to reuse old XML files if the related SNMP devices +are not reachable and the files are not older than DAYS. + +If an SNMP device is unreachable by the moment of the collector initialization, +the collector reports the error and waits for a period of time specified in +C<$Torrus::Collector::SNMP::unreachableRetryDelay>, which is 10 minutes by +default. It then tries to reach the device with the specified retry interval +during some period of time, defined in +C<$Torrus::Collector::SNMP::unreachableTimeout>, by default 6 hours. +If the device is not available within the specified timeout, it is excluded +from collection. It would be tried again on collector initialization +only (at the collector process start or after recompiling the configuration). + +If a device is not reachable during the normal collector running cycle, +it is retried in every collector's cycle (usually every 5 minutes), +during the period defined in C<$Torrus::Collector::SNMP::unreachableTimeout>. +It will be then excluded from configuration after the timeout. + +If a device hardware configuration changes after the C<devdiscover> +execution, the collector may not find some values in SNMP tables, +such as interface names in ifTable. It then excludes such datasources from +collection immediately. + + + + +=head2 Tips and tricks + + +=head3 Comments, descriptions, and legends + +C<torrus devdiscover> will extract some useful information from +your SNMP devices, and place it in the XML configuration: + +=over 4 + +=item * Interface descriptions + +The value of the SNMP variable C<ifAlias> (C<1.3.6.1.2.1.31.1.1.1.18>) +will be used as interface comment. In Cisco IOS, this is controlled by +C<description> interface configuration command. + +=item * Location and contact + +Two other SNMP values: C<sysLocation> (C<1.3.6.1.2.1.1.6.0>) and +C<sysContact> (C<1.3.6.1.2.1.1.4.0>) will be used in the legend text +for each device. In Cisco IOS, their values are controlled by +C<snmp-server location> and C<snmp-server contact> global configuration +commands. + +=back + + +=head3 Grouping the datasources alternatively + +In most cases, you would want to have several different groupings of +your datasources. + +For instance, the default C<devdiscover> gives only one level of freedom: +the subtree name above the host level. It's reasonable to use this name for +grouping by geographical location . Thus, the hierarchy +would be characterised as +C</[location]/[hostname]/[interface]/[counter]>. + +Let's say you would like to have alternative grouping, such as: + +=over 4 + +=item * by customer connection: + +Each customer is identified by name, and you'd like to see statistics +for all interfaces connected to a given customer; + +=item * by service: + +Your network is designed to provide various services, and you'd like to +group your devices or interfaces by service; + +=item * by customer and location: + +For each customer, group the connection by geographical location. + +=back + +Torrus provides three different ways for organising your datasources: + +=over 4 + +=item * Aliases. + +With C<E<lt>aliasE<gt>> statement, you can add symbolic names to your +nodes. If the new alias is defined as a reference to non-existing subtree, +the new subtrees are created. Alias is only a symbolic link: when you click +to the alias name in your browser, Torrus redirects it to the real datasource +in its normal subtree. See the example in I<Torrus XML Configuration Guide>. + +=item * ds-type=rrd-file + +You can create a leaf in some arbitrary place of your hierarchy that +points to an existing RRD file. This RRD file may be updated by +other datasource in your hierarchy. The advantage of such approach is +that this leaf may have its own I<legend> and I<comment> parameters, +alternative view parameters, etc. + + <leaf name="FoobarIn"> + <param name="ds-type" value="rrd-file" /> + <param name="leaf-type" value="rrd-def" /> + <param name="data-file" value="rtr01_Fa0_1.rrd" /> + <param name="rrd-cf" value="AVERAGE" /> + <param name="rrd-ds" value="locIfInBitsSec" /> + <param name="comment" + value="Foobar input traffic"/> + <param name="graph-legend" value="Bits in" /> + <param name="legend"> + Switch name: rtr01; Interface: Fa0/1; + </param> + </leaf> + +In the example above, this leaf is defined somewhere in the hierarchy. +It refers to the RRD file updated by Torrus SNMP collector. +For more examples, see the template I<read-cisco-interface-counters> +in F<vendor/cisco.ios.xml>. + +=item * Tokensets + +Tokenset is an arbitrary collection of datasource leaves. It is characterised +by its name and description. There are two ways to add a leaf to a tokenset: +by the parameter I<tokenset-member>, or by defining a monitor action. +A tokenset is normally displayed in compact form: by default, 6-hour graphs +are put by two in a row. + +=back + + +=head3 Amending autogenerated XML files with XUpdate + +Sometimes there is a need to modify the configuration generated by +C<devdiscover>. Modifying the generated XML files by hand would not be +a good option: it would need some manual work every time you update +your hardware setup. A better approach would be to have the tools +that would automate such configuration update. + +One of the possibilities for such automation would be XSLT +E<lt>http://www.w3.org/TR/xsltE<gt>. But it's rather +complicated task to use XSLT for slight changes in XML files. + +A good approach has been made by XUpdate Working Group +E<lt>http://www.xmldb.org/xupdate/E<gt>. Their Working Draft document +describes a language for XML editing commands. It allows to perform +small updates to an existing XML document, like insertion of elements, +updating of existing elements, or deleting. The only drawback is +that the specification hasn't been updated since September 2000, +and it contains some unclear statements, which make it difficult to +implement compatible applications. In addition, there has been +not enough efforts to adopt XUpdate as a W3C standard. +However, this is the only kind-of-a-standard language for such tasks as +XML editing commands. + +Thanks to Petr Pajas, there is an XUpdate implementaytion in Perl. +C<XML::XUpdate::LibXML> module is available at CPAN, and it installs +a small commandline utility, C<xupdate>. In addition, Petr has created +a set of utilities integrated into a single shell wrapper: +E<lt>http://xsh.sourceforge.netE<gt>. It is very useful for many different +things, such as XPath expressions testing, and many others. + +A typical XUpdate instructions file would looke like follows: + + <?xml version="1.0"?> + <xupdate:modifications version="1.0" + xmlns:xupdate="http://www.xmldb.org/xupdate"> + + <!-- Insert additional creator-info after the last one --> + <xupdate:insert-after + select="/configuration/creator-info[not(following-sibling::creator-info)]"> + <creator-info> + This file was modified with XUpdate script setmonitor.xupdate.xml + </creator-info> + </xupdate:insert-after> + + <!-- For every ifError leaf, set the monitor --> + <xupdate:append select="//subtree[apply-template[@name='iftable-errors']]"> + <xupdate:element name="subtree"> + <xupdate:attribute name="name">ifErrors</xupdate:attribute> + <param name="monitor" value="check-iferrors"/> + </xupdate:element> + </xupdate:append> + + </xupdate:modifications> + +This example is part of Torrus distribution, and the file is named +F<examples/setmonitor.xupdate.xml>. Your commands to apply these XUpdate +instructions would be like + + torrus devdiscover --in=routers.ddx --out=routers.xml + + cd @sitexmldir@ + xupdate -j @exmpdir@/setmonitor.xupdate.xml \ + routers.xml > routers1.xml + +More XUpdate examples will be included in the future. + + +=head3 Extracting the configuration skeleton + +Another aproach to amending the autogenerated confguration is as follows. + +Torrus distribution has a special-purpose XSLT template, +F<extract-skeleton.xsl>, designed to strip all parameters and template +applications from a given XML configuration, and leave the tree structure +only. Given that F<routers.xml> is some autogenerated configuration, +you may run + + xsltproc @scriptsdir@/xml/extract-skeleton.xsl routers.xml | \ + xmllint --format --output routers-skeleton.xml - + +You can add your changes to the new file, F<routers-skeleton.xml>, and add +it to your Torrus configuration. These changes may be performed manually +or by means of XUpdate technique described above. + + +=head3 Automating XML generation + +It is quite common task that you want Torrus to monitor certain set of +devices, and C<devdiscover> does not (yet) support them. Of course, +it's quite a pain to maintain a manually written XML file, especially if +the there are more than one devices of the same type. + +In such case you may benefit from the approach suggested by +Christian Schnidrig: + +Imagine you have 50 I<gizmos> which are able to speak SNMP and which you would +like to put into some Torrus tree structure. A good designer's approach would +be to keep the data and the presentation separately. In addition, changing +the presentation once would produce 50 changes accordingly. +To do that, let's create two files: F<gizmos.data> and F<gizmos.tmpl>. +The first one would contain data about our devices: + + [% + gizmos = [ + { + name => 'atwork' + color => 'blue', + location => 'Javastrasse 2, 8604 Hegnau' + description => 'My gizmo @ Sun' + community => 'blabla', + hands => [ + {name => 'Left'} + {name => 'Right'} + ], + } + { + name => 'athome' + color => 'gray', + location => 'Riedstrasse 120, 8604 Hegnau' + description => 'My gizmo @ Home' + community => 'blabla', + hands => [ + {name => 'Upper'} + {name => 'Lower'} + ], + } + ] + + %] + +Then F<gizmos.tmpl> would contain the XML template that would produce +the Torrus configuration file: + + [% PROCESS $data %] + <?xml version="1.0"?> + <configuration> + <datasources> + <subtree name="SNMP"> + <subtree name="Gizmos"> + [% FOREACH g = gizmos %] + <!-- ******************************************************* --> + <!-- [% g.name %] --> + <subtree name="[% g.color %]"> + <alias>/ByName/[% g.name %]/</alias> + + <param name="snmp-community" value="[% g.community %]" /> + <param name="comment" value="[% g.description %]" /> + <param name="snmp-host" value="[% g.name %]" /> + <param name="legend"> + Description: [% g.description %] + Location: [% g.location %] + </param> + + [% FOREACH h=$g.hands %] + <leaf name="[% h.name %]Hand"> + <!-- do something, my fantasy exhausted here --> + </leaf> + </subtree> + [% END %] + </subtree> + </subtree> + </datasources> + </configuration> + +See F<xmlconfig/examples/servers.data> and F<xmlconfig/examples/servers.tmpl> +for a more useful example of the described approach. + +At the end, you will generate the Torrus config with the C<tpage> utility, +which is the standard part of Template-Toolkit package: + + tpage --define data=gizmos.data gizmos.tmpl > gizmos.xml + + +=head3 Several Torrus instances on one server + +Sometimes it is necessary to have a separate instance of Torrus for testing +purposes on the same server as the production installation. +In the example below, a completely autonomous installation of Torrus is +installed in F</usr/testtorrus> directory on a FreeBSD system. + +=over 4 + +=item * Directory structure + +All files are located in subdirectories of F</usr/testtorrus>. No other +directories are affected. This ensures that deinstallation would be easy +and safe. + +Four subdirectories are created: + +=over 8 + +=item * F</usr/testtorrus/apache> + +This directory contains Apache HTTP daemon configuration and logs. Create 3 +subdirectories here: F<etc>, F<htdocs>, and F<var>. + +=item * F</usr/testtorrus/home> + +This is the installation directory of Torrus. + +=item * F</usr/testtorrus/etc> + +Directory for configuration files. + +=item * F</usr/testtorrus/var> + +Directory for logs, database and PID files. + +=item * F</usr/testtorrus/collector_rrd> + +Collector will store RRD files here. + +=item * F</usr/testtorrus/src> + +Distribution files will be stored and unpacked here. + +=back + + +=item * Installation procedure + + cd /usr/testtorrus/src + gzip -dc torrus-1.0.0.tar.gz | tar xvf - + cd torrus-1.0.0 + ./configure pkghome=/usr/testtorrus/home \ + sitedir=/usr/testtorrus/etc \ + logdir=/usr/testtorrus/var/log \ + piddir=/usr/testtorrus/var/run \ + varprefix=/usr/testtorrus/var \ + wrapperdir=/usr/testtorrus + make install + +=item * Devdiscover configuration + +Use devdiscover as usual. Place your discovery instruction files in +F</usr/testtorrus/etc/discovery/>, and make sure that +C<data-dir> is set to F</usr/testtorrus/collector_rrd>. + +=item * Apache configuration + +We reuse the same binaries and libraries as the main installation of Apache, +but the daemon is launched with our special configuration. +We assume that Apache is pre-configured for mod_perl. SSL support is not +included in this example, but it's quite straightforward to implement +if you need it. + +Create a copy of F<httpd.conf> and place it in F</usr/testtorrus/apache/etc>. +With a text editor, replace the configutration options with the values +given below: + + # Leave server root as it was in the original config. Apache uses + # it for modules loading + ServerRoot "/usr/local" + + # make sure that everything that apache writes + # goes into our directories + PidFile /usr/testtorrus/apache/var/httpd.pid + ScoreBoardFile /usr/testtorrus/apache/var/httpd.scoreboard + + # Optional: limit the memory and CPU impact + MinSpareServers 2 + MaxSpareServers 5 + StartServers 3 + MaxClients 10 + + # We open our HTTP service on TCP port 8123. Choose other + # port if this one is occupied + Port 8123 + + # Not really necessary, but you might want to use it someday + DocumentRoot "/usr/testtorrus/apache/htdocs" + + # Find the Directory options for the old htdocs, and + # replace the path if you changed DocumentRoot above + <Directory "/usr/testtorrus/apache/htdocs"> + ... some default stuff here ... + </Directory> + + # Make sure the logs are written where we expect them to. + ErrorLog /usr/testtorrus/apache/var/httpd-error.log + CustomLog /usr/testtorrus/apache/var/httpd-access.log combined + + # TCP port number as above + NameVirtualHost *:8123 + + # Quite standard virtual server configuration. Replace fake + # domain names with your real ones. + <VirtualHost *:8123> + ServerAdmin root@myserver.com + DocumentRoot /usr/testtorrus/home/web + ServerName torrus.myserver.com + CustomLog /usr/testtorrus/apache/var/torrus.myserver.com.log "combined" + PerlModule Apache::PerlRun + PerlRequire "/usr/testtorrus/home/conf_defaults/webmux.pl" + Alias /plain/ "/usr/testtorrus/home/sup/webplain" + <Location /> + SetHandler perl-script + PerlHandler Torrus::ApacheHandler + </Location> + <Location /plain/> + SetHandler default-handler + Options None + </Location> + </VirtualHost> + +=item * Apache startup script + +Save the following script as F</usr/testtorrus/apache/testtorrus.sh>: + + #!/bin/sh + case "$1" in + start) + /usr/local/sbin/httpd -f /usr/testtorrus/apache/etc/httpd.conf && \ + echo 'apache started' + ;; + stop) + [ -r /usr/testtorrus/apache/var/httpd.pid ] && \ + kill `cat /usr/testtorrus/apache/var/httpd.pid` && \ + echo 'apache stopped' + ;; + *) + echo "Usage: `basename $0` {start|stop}" >&2 + ;; + esac + exit 0 + +=back + + +=head3 Changing the default short graph + +The default small graph in overviews and tokenset listings shows last 6 hours +of data. It might be more convenient for you to graph last 24 hours, +or even longer. To do so, you only need to change one parameter, +C<rrgraph-views>. You may change it on the top of the datasource tree, or +even only for some parts of the tree. + +In F<defaults.xml>, there's a view defiition called C<last24h-small>. It is +exactly the same size as the 6-hours' C<short> view, but it shows 24-hour +graph. Somewhere in Torrus configuration, you may have: + + <datasources> + <param name="rrgraph-views"> + last24h-small,last24h,lastweek,lastmonth,lastyear + </param> + </datasources> + +The best place for this would be F<site-global.xml>. + + +=head3 Watching the collector failures + +There is a script in Torrus distribution in F<examples/rrdup_notify.sh>, +which provides a simple way of telling if the collector runs right: it checks +the modification time of RRD files, and if any file is older than given +threshold, it sends an e-mail warning. + +Copy the script file to some place in your system and edit it so that it fits +your requirements: you might want to change the maximum age +parameter (default is 1 hour), the notification e-mail address, and the +directory paths where to look for RRD files. Then I<chmod> it so that it's +executable, and add it to I<crontab>. Depending on your operation requirements, +it might run every hour, or few times a day, or even at business hours only. + +The script writes the number of aged files in the e-mail subject, and lists +the file names in the body. In case of relatively large installation, +you might want to amend the script, in order to avoid too large email messages. + + +=head3 Viewing external RRD files + +Some external program may create its own RRD files, and you +may want to display and monitor them in Torrus. + +Also some collector-generated RRDs may become outdated -- for example, after +a module is removed from a router, and the interface counters not +being updated any more. + +The easiest way to use such files would be to utilize the +C<torrus rrddir2xml> command. It generates the XML configuration file +that represents all RRD files found in a given directory. It can also +scan the directory recursively. + +See also few examples in Torrus distribution. There are some +templates for use with Smokeping, OpenNMS, and Flowscan. + + +=head2 Torrus usage scenarios + + +=head3 Scenario 1. Netflow Traffic Analyser + +Cisco routers are capable of exporting the traffic statistics +data in I<Netflow> UDP packets. + +A I<cflowd> or I<flow-tools> daemon collects Netflow packets into flow files. + +I<FlowScan> software analyses the flow files and stores the +statistics into numerous RRD files. + +Torrus is used to monitor the thresholds and diplay the graphs +in convenient form. + + +=head3 Scenario 2. Backbone Traffic Statistics + +I<CiscoWorks2000> or I<NMSTOOLS> software is used to provide +the list of all devices in the network. + +Torrus's C<devdiscover> buids the XML configuration to monitor the +router interfaces, CPU and memory usage, and temperature sensors. + +Data importing scripts generate configuration for alternative +grouping of the datasources: by location; by customer connection; +by device type; by service type; etc... + + +=head2 Troubleshooting guidelines + +=head3 SNMP Error: Received tooBig(1) + +For some devices, the collector may issue the following error messages: + + [27-May-2004 10:15:17*] SNMP Error for XX.XX.XX.XX:161:public: Received + tooBig(1) error-status at error-index 0 + +For better performance, SNMP collector sends several SNMP requests in one +UDP datagram. The SNMP agent then tries to send the reply to all requests +in a single datagram, and this error indicates the failure. In most cases, +this is caused by the agent software limitations or bugs. + +The number of requests per datagram is controlled by the parameter +C<snmp-oids-per-pdu>, and it may be set in the discovery input XML or +in Torrus configuration XML. The default value is 40, and setting it to 10 +generally works. + +=head3 Database lock troubleshooting + +It may happen sometimes, that a process accessing Torrus database +terminates incorrectly, and the database becomes blocked. +A typical symptom of this is that the command +C<torrus compilexml --all --verbose> +does not print anything and stays running forever, occupying zero +percent of CPU. + +The nice, and the preferred way to solve the problem is +to use C<db_recover> utility from BerkeleyDB package. +The brutal way is just to remove the databases and re-compile +all the configuration. I<Note:> The ACL database is not automatically +backed up, and you need to take care of its backup before deleting +the contents of the database. + + ## The nice way uses BerkeleyDB db_recover + ## (might be located in /usr/local/BerkeleyDB.4.1/bin/) + /etc/init.d/apache stop + /etc/init.d/torrus stop + db_recover -h @dbhome@ + torrus compilexml --verbose --all + /etc/init.d/torrus start + /etc/init.d/apache start + + ## The brutal way + /etc/init.d/apache stop + /etc/init.d/torrus stop + cd @dbhome@ + rm -r * + torrus compilexml --verbose + /etc/init.d/torrus start + /etc/init.d/apache start + +=head1 Author + +Copyright (c) 2002-2007 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> diff --git a/torrus/doc/vendorsupport.pod.in b/torrus/doc/vendorsupport.pod.in new file mode 100644 index 000000000..cbc313c08 --- /dev/null +++ b/torrus/doc/vendorsupport.pod.in @@ -0,0 +1,222 @@ +# Copyright (C) 2004 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: vendorsupport.pod.in,v 1.1 2010-12-27 00:04:31 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 Torrus Vendor Support List + +=head2 Introduction + +This document provides a listing of vendor devices and generic MIBs +that are suppported by Torrus'es SNMP discovery utilities and/or templates +and other supporting files. + +All SNMP MIBs described below are supported through C<devdiscover>, +the SNMP discovery utility. Where possible, the system contact, location, +and interface descriptions are copied to the generated Torrus configuration. + + +=head2 Generic SNMP MIBs + +=over 4 + +=item * RFC1628 (UPS-MIB) + +Generic statistics covered by most UPS manufactures, including input, output, +and bypass group information. + +=item * RFC1697 (RDBMS-MIB) + +Provides the database engine performance statistics. Tested with Oracle only. + +=item * RFC2662 (ADSL-LINE-MIB) + +ADSL DSLAM statitics and line status. Tested with Paradyne DSLAM. + +=item * RFC2670 (DOCS-IF-MIB) + +DOCSIS cable status and statistics. Tested with Cisco uBR. + +=item * RFC2737 (ENTITY-MIB) + +Used to retrieve information about chassis and temperature sensors in Cisco +devices. + +=item * RFC2790 (HOST-RESOURCES-MIB) + +Server CPU, memory, and disk statistics. Tested with net-snmp and MS Windows. + +=item * RFC2863 (IF-MIB) + +Generic network interface statistics from C<ifTable> and C<ifXTable>. +Most servers and network devices support this MIB. Featuring custom +vendor-dependent indexing and interface type/name filtering. +Tested with many different vendors. + +=back + +=head2 Vendor-specific SNMP monitoring + +=over + +=item * Alteon content switches + +Application switching and performance statistics. + +=item * Allied Telesyn PBC18 Media converter + +Reports the line status for the manageable modular media converter. + +=item * Arbor Networks + +Provide statistics for Arbor eSeries devices. (e30, e100) + +=item * Ascend MAX + +Provides statistics for analog and ISDN interfaces, and the total number +of lines used. + +=item * Atmel wireless access points and bridges + +Privides link quality and traffic statistics for wireless devices. +The discovery process would run very slow unless you specify the +following parameter in the discovery instructions XML: + + <param name="only-devtypes" value="ATMEL"/> + +=item * AxxessIT Ethernet over SDH switches (aka Cisco ONS 15300) + +The module arranges the Ethernet interface statistics with +such information as slot/port mapping and interface descriptions. + +=item * BetterNetworks EthernetBox + +The discovery module detects active sensors in an EthernetBox sensor module. + +=item * Brocade (Foundry) + +A variety of Foundry switches and routers is supported for memory, +CPU, and temperature statistics. + +=item * CASA Systems CMTS + +Modem quantities per upstream, downstream, MAC domain. + +=item * Cisco CatOS + +Memory, CPU, and temperature information. Per-interface statistics may be +limited to the ports with description only. + +=item * Cisco IOS + +Provides per-interface traffic statistics; CPU, memory, and +temperature information; I/O buffer statistics; IPSec traffic information; +SAA agents statistics; cbQoS monitoring (implemented in a separate plugin); +DOCSIS uBR-specific variables (modem quantities and channel utilization); +CISCO-ENHANCED-MEMPOOL-MIB (linecards and VIP modules memory, see notes below); +MAC accounting statistics (associated with BGP AS numbers when applicable); LRE +and VDSL line statistics; BGP prefix counts (http://tinyurl.com/y3ganv); +CAR statistics; VPDN Statistics. + + +B<Note:> On Cisco 7500, IOS version 12.0(26)S2 or 12.0(26)S3, +CISCO-ENHANCED-MEMPOOL-MIB polling causes memory leak and leads to the router +crash (Bug ID CSCef53395). The problem is fixed in IOS versions +12.0(26)S5, 12.0(27)S3, 12.0(28)S2, and 12.0(30)S. + + +=item * Cisco PIX Firewall + +Firewall performance statistics. + +=item * Cisco SCE + +Service Control Engine performance statistics. + +=item * Compaq Insite Manager + +Temperature and memory health information statistics for Compaq servers. + +=item * Empire (Concord) SystemEDGE + +Provides lots of statistics and information that a SystemEDGE agent +may provide about the server health and performance. + +=item * F5 BigIp Load Balancer + +In-detail traffic statistics. + +=item * Force10 Networks + +CPU, Temperature and Power supply statistics. + +=item * Jacarta iMeter + +Humidity, Temperature, Electric current meters. + +=item * Juniper JunOS + +Class of service, firewall, operating environment, reverse path forwarding, +and interface statistics. + +=item * Liebert HVAC systems + +Temperature, humidity and system state sensors + +=item * Microsoft Windows 2000/XP + +Sets up proper interface indexing and provides FTP and HTTP server statistics. + +=item * Motorola BSR CMTS (ex-Riverdelta) + +Displays modem quantities. + +=item * NetApp.com storage products + +Storage arrays performance and health information. + +=item * NetScreen Firewall + +Firewall performance statistics. + +=item * Oracle + +Database engine statistics. + +=item * Paradyne GranDSLAM + +xDSL statistics and line status. + +=item * Symmetricom NTP appliance + +NTP clock statistics + +=item * UCD SNMP and Net-SNMP + +Memory, CPU, and disk usage information. + +=item * Xylan ethernet switches + +Port indexing for OmniSwitch and OmniStack ethernet switches. + +=back + +=head1 Author + +Copyright (c) 2004-2005 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> diff --git a/torrus/doc/webintf.pod.in b/torrus/doc/webintf.pod.in new file mode 100644 index 000000000..f85d99435 --- /dev/null +++ b/torrus/doc/webintf.pod.in @@ -0,0 +1,280 @@ +# webintf.pod - Torrus web interface reference +# Copyright (C) 2002 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: webintf.pod.in,v 1.1 2010-12-27 00:04:33 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 Torrus Web Interface Reference + +B<Warning:> This documentation is relevant to Torrus version 1.0.9. +It is incompatible with previous versions. + +=head2 Directory structure + +By default, the directory F<@webplaindir@/> is the place +for static HTML, CSS stylesheets and images. + +The default CSS stylesheet files are installed in this directory. +This directory must be configured with I<SetHandler default-handler> +directive. + +=head2 CSS Stylesheets + +Additional user-defined stylesheet files may be added in +F<webplain> directory. +The default HTML templates that come with the Torrus distribution use the +global configuration variable C<$Torrus::Renderer::stylesheet>, which is set +in F<torrus-config.pl> and may be overwritten in F<torrus-siteconfig.pl>. + +=head2 Cache files + +All generated HTML and graphical images are cached twice: first on the server, +and then in your browser. Thus, if you change somehow the HTML +appearance of your Torrus installation, you need to clean both caches: + + torrus clearcache + +This will clear the cache on the server. Then you may use your browser's +"reload" button, or clear the whole browser cache. + + +=head2 Site configuration options + +The following variables may need to be set in your +F<@siteconfdir@/torrus-siteconfig.pl> file: + +=over 4 + +=item * C<$Torrus::Renderer::companyName> + +The text that you specify here will appear in the top left corner +of all HTML pages. + +=item * C<$Torrus::Renderer::companyURL> + +The company name text will be clickable with the URL specified in +this variable. + +=item * C<$Torrus::Renderer::rendererURL> + +Default: C<'/torrus'>. A URL that points to Torrus renderer. + +=item * C<$Torrus::Renderer::plainURL> + +Default: C<'/torrus/plain'>. A URL that points to Torrus plain files directory. +Normally CSS stylesheet files are resided there.. + +=item * C<$Torrus::CGI::authorizeUsers> + +Default: C<1>. When true, the web interface users are required to log in. + +=back + + +=head2 mod_perl 1.0 handler: Torrus::ApacheHandler + +For more documentation, see E<lt>http://perl.apache.org/E<gt>. + +The whole output generation is performed by the C<Torrus::ApacheHandler> class. +However, you still need access to the F<plain> directory where your CSS +resides. Typical Apache configuration would look like follows. Make sure +your configuration does not contain tab characters: + + PerlRequire "@cfgdefdir@/webmux.pl" + <Location /torrus> + SetHandler perl-script + PerlHandler Torrus::ApacheHandler + </Location> + +The base URL would be in this case: + + http://yourhost/torrus/ + + +=head2 mod_perl 2.0 handler: Torrus::Apache2Handler + +I<Note:> Apache 2.0 support in Torrus is currently in its early +development stage. + +I<Note:> As of now, C<libapreq2> library is not released yet, and only the +development version is available. You have to download and install it +manually. + +mod_perl version B<1.99_15> or later is supported. To the moment, +C<libapreq2> version C<2.04_03-dev> is tested. + +Make sure you use C<webmux2.pl> and C<Torrus::Apache2Handler> in your +configuration. + +C<SetHandler modperl> directive should give better performance +than C<SetHandler perl-script>. Both Perl handlers work the same way +with Torrus. + +Typical Apache 2.0 configuration follows: + + PerlRequire "@cfgdefdir@/webmux2.pl" + <Location /torrus> + SetHandler perl-script + PerlResponseHandler Torrus::Apache2Handler + </Location> + +The base URL would be in this case: + + http://yourhost/torrus/ + + +=head2 lighttpd with FastCGI handler + +As of version 1.0.9, Torrus supports FastCGI server module. It is also often +used together with B<lighttpd> HTTP server. + +Install FastCGI on your server, and also F<FCGI> module from CPAN. + +Add user "lighttpd" to group "torrus". + +The following configuration creates a virtual host, so that any URL which +starts with "tor" would result in Torrus display: + + # Uncomment mod_redirect and mod_fastcgi. Other modules might be needed too. + server.modules = ( + "mod_redirect", + "mod_fastcgi", + ) + # virtual server configuration + $HTTP["host"] =~ "^tor" { + url.redirect = ( "^/$" => "/torrus" ) + fastcgi.server = ( + "/torrus" => ( + "Torrus" => ( + "socket" => "/tmp/Torrus_FCGI.socket", + "check-local" => "disable", + "bin-path" => "@pkgbindir@/torrus.fcgi", + "max-procs" => 2, + ) + ) + ) + } + + +=head2 Apache 2.0.x with FastCGI handler + +As of version 1.0.9, Torrus supports the FastCGI server module. +It is also often used together with B<Apache 2.x> HTTP server. + +The following is an example of a virtual host with four FastCGI child processes + + + <VirtualHost *:80> + DocumentRoot "/var/www/vhosts/test01.torrus.net" + ServerName test01.torrus.net + AddHandler fastcgi-script fcgi + FastCgiServer @pkgbindir@/torrus.fcgi \ + -processes 4 + ScriptAlias /torrus "@pkgbindir@/torrus.fcgi" + <Location /torrus> + Order Allow,Deny + Allow from all + </Location> + </VirtualHost> + + + +=head2 Known CGI parameters + +The following CGI parameters are recognized by mod_perl handler: + +=over 4 + +=item token + +Optional. Each configuration tree element is referenced by a I<token>, a short +unique identifier. If not given, the root of the tree (C</>) is displayed. + +=item path + +Optional. Alternatively to token reference, the full path of the tree element +may be referenced. + +=item nodeid + +Optional. A subtree which has a unique I<nodeid> can be referred +with this parameter. + +=item view + +Optional. Specifies the C<view> name for displaying the tree element. +If not specified, the defaul view is used. + +=item v + +Optional. Synonym for C<view> parameter. + + +=item hostauth + +Mandatory for host-based authentication. The value is treated as a password +and the user name is the client's IP address with non-alphanumerics +replaced with underscores. + + +=item TZ + +Optional. If given, specifies the timezone that you want the graphs to be +displayed for. This must be the URL-encoded zone name which is understood by +your server system. You may use zdump(8) for testing. + +=item NOW + +Optional. If given, presents the output for the given moment, instead of the +current time. Must be of the form understood by C<rrdtool> (see +RRDTool manuals). + +=item Gstart, Gend, Gwidth, Gheight + +Optional vaiables that override the ones defined in the view. + +=item DEBUG + +Optional. If true, turns on the debug level of logging. The debug messages +are sent to HTTP server's error log. + +=item SHOWHIDDEN + +Optional. If true, makes the grapher display those subtree and leaves +which have C<hidden> parameter set to C<yes>. + +=item NOHW + +Optional. If true, disables the displaying of Holt-Winters +boundaries and failures. + +=item LOGOUT + +Optional. When user authorization is enabled, causes the current user +session to log out. + +=back + +All other parameters whose name starts with capital letter, are passed +to the HTML template as-is, and may be used for your custom purposes. + + +=head1 Author + +Copyright (c) 2002-2005 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> diff --git a/torrus/doc/xmlconfig.pod.in b/torrus/doc/xmlconfig.pod.in new file mode 100644 index 000000000..f1ae4350c --- /dev/null +++ b/torrus/doc/xmlconfig.pod.in @@ -0,0 +1,1725 @@ +# xmlconfig.pod - Torrus configuration guide +# Copyright (C) 2002 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: xmlconfig.pod.in,v 1.1 2010-12-27 00:04:34 ivan Exp $ +# Stanislav Sinyagin <ssinyagin@yahoo.com> +# +# + +=head1 Torrus XML Configuration Guide + +=head2 Common rules + +The Torrus configuration consists of several XML files. +Once the XML configuration is changed, it must +be compiled into the database by executing C<torrus compilexml>. +In addition, when I<Renderer>, I<Collector> and I<Monitor> processes +notice the configuration changes, they refresh their information automatically. + +The top-level XML element is always C<E<lt>configurationE<gt>>, with +sub-elements defining various sections, like datasources or views: + + <configuration> + + <!-- Optional inclusion of other XML files --> + <include filename="myconfig.xml"/> + + <datasources> + <!-- Data sources tree definition --> + ... + </datasources> + <views> + <!-- View definitions --> + ... + </views> + <token-sets> + <!-- Token sets definitions -> + ... + </token-sets> + <monitors> + <!-- Monitor definitions -> + ... + </monitors> + </configuration> + +Multiple XML files are interpreted in additive matter, i.e. +C<E<lt>datasourcesE<gt>> section from one file is concatenated with +the corresponding sections of previous files. If the same +parameter is defined for the same subtree in several input files, +the last processed value gets into the configuration. + +Additional XML files may be added to the compilation list by means of +C<E<lt>includeE<gt>> statement. They will be processed recursively +before the content of the XML file they are referenced from. +The argument C<filename> determines the +name of the file in standard XML files directory. +It is safe to include the same file several times, +Torrus compiler guarantees that files are only processed once. + +Some kinds of sections, like C<E<lt>datasourcesE<gt>>, allow to +define the same elements two or more times. In this case, +the previous parameter values are overridden by the new values. + +Each component of the configuration is defined by the set of I<parameters>. +They are specified in a common manner, differentiating in parameter names only: + + <view name="default-rrd-html"> + <param name="view-type" value="html" /> + <param name="expires" value="300" /> + <param name="html-template" value="default-rrd.html" /> + </view> + +The parameter value can be specified either by C<value> XML attribute, +or by the text contents of the C<E<lt>paramE<gt>> element. + +Some parameter values require other parameters to be defined, like in the +above example: a view of type C<html> cannot exist without a template. + +After I<all> XML files are compiled, the parameters are checked for validity +by the compiler. + +=head2 Character sets + +By default, all XML input is treated as UTF-8 (unicode). This is important +because all the HTML output generated by Torrus is encoded UTF-8. + +However, you may use Latin1 (ISO-8859-1) encoding in your XML files. +In order to ensure correct displaying of non-ASCII characters, +the encoding must be specified in your XML files: + + <?xml version="1.0" encoding="ISO-8859-1"?> + +You need this only in those files containing non-ASCII characters +in Latin1 encoding. + +In addition, version C<1.54_3> or higher of C<XML::LibXML> is required, and +Torrus version 0.0.16 or above. + + +=head2 Macros + +In the top level of the configuration tree, a number of macros may be defined. +Currently they are used in C<snmp-object> parameter only. +Macros are specified with C<E<lt>defE<gt>> elements, being the direct +children of C<E<lt>definitionsE<gt>> element: + + <configuration> + <definitions> + <!-- IF-MIB:ifTable --> + <def name="ifDescr" value="1.3.6.1.2.1.2.2.1.2" /> + <def name="ifPhysAddress" value="1.3.6.1.2.1.2.2.1.6" /> + <def name="ifInOctets" value="1.3.6.1.2.1.2.2.1.10" /> + <def name="ifInUcastPkts" value="1.3.6.1.2.1.2.2.1.11" /> + <def name="ifInErrors" value="1.3.6.1.2.1.2.2.1.14" /> + <def name="ifOutOctets" value="1.3.6.1.2.1.2.2.1.16" /> + <def name="ifOutUcastPkts" value="1.3.6.1.2.1.2.2.1.17" /> + <def name="ifOutErrors" value="1.3.6.1.2.1.2.2.1.20" /> + + <!-- Default Interface index lookup --> + <def name="IFIDX" value="M($ifDescr, %interface-name%)" /> + </definitions> + ... + +These definitions are global across all XML configuration files, +and are referenced with dollar sign and the definition name, e.g.: + + <leaf name="ifInErrors"> + <param name="snmp-object" value="$ifInErrors.$IFIDX" /> + ... + + +=head2 Parameter properties + +Some parameters require special handling during the compilation or +at the runtime. The parameter properties define such behaviour in the +XML configuration. + +Currently two properties are recognized: "remspace" and "expand". + + <configuration> + <param-properties> + <!-- Parameters where space is removed from values --> + <prop param="action" prop="remspace" value="1"/> + <prop param="display-rpn-expr" prop="remspace" value="1"/> + <prop param="ds-names" prop="remspace" value="1"/> + ... + </param-properties> + + + +=head2 Datasource definitions + +Datasources are organized into a tree hierarchy. All parameters are inherited +by the subtrees and leafs from their parents, and can be overridden on +lower levels. + +The datasources tree consists of two key types of components: +I<subtree> and I<leaf>. A subtree can have child subtrees or leaves. +A leaf can never have children. A subtree represents logical aggregation, +while the leaf always represends the actual datasource. + +In XML configuration, a child subtree or leaf belongs to the parent +element, like the following: + + <datasources> + <!-- This is the first child of the tree root --> + <subtree name="Netflow"> + <param name="ds-type" value="rrd-file" /> + <param name="comment" + value="Netfow data collected by FlowScan with CarrierIn.pm" /> + <!-- All Flowscan-generated files reside here --> + <param name="data-dir" value="/var/local/flowscan/graphs" /> + <subtree name="Exporters"> + <param name="comment" value="Netflow exporting devices" /> + ... + <!-- all exporters defined here --> + </subtree> + ... + <subtree name="Total"> + <param name="data-file" value="total.rrd" /> + <leaf name="bps"> + <param name="comment" value="Bits per second" /> + <param name="leaf-type" value="rrd-def" /> + <param name="rrd-ds" value="bits" /> + <param name="rrd-cf" value="AVERAGE" /> + </leaf> + <leaf name="pps"> + <param name="comment" value="Packets per second" /> + <param name="leaf-type" value="rrd-def" /> + <param name="rrd-ds" value="pkts" /> + <param name="rrd-cf" value="AVERAGE" /> + </leaf> + <leaf name="packlen"> + <param name="comment" value="Average packet length in bytes" /> + <param name="leaf-type" value="rrd-cdef" /> + <param name="rpn-expr" value="{bps},8,/,{pps},/" /> + </leaf> + </subtree> + </subtree> + </datasources> + + +Each subtree or a leaf is identified by a I<path>, the symbolic +notation similar to filesystem paths. In any path notation, +subtree names always end with slash (/), and this trailing slash is +the part of the name. In this case, any subtree is identified by a path +ending with slash, while leaf paths always end with a word symbol. +The top-level subtree is identified by a single slash. + +The other components of the datasouce definition are I<templates> and +I<aliases>. + +=head3 Templates + +A template is used when it's needed to define multiple different pieces of +the configuration in the same way. For instance, the definition for +input/output octets and bits can be specified once in a template, +and then applied where appropriate. + +The piece of XML configuration inside the C<E<lt>templateE<gt>> +element is memorized under the template name, and reproduced +in every occurrence of C<E<lt>apply-templateE<gt>> with the corresponding +template name. The template definition must be the direct child +element of C<E<lt>configurationE<gt>> XML element: + + <datasources> + <!-- Default views must be defined --> + <param name="default-subtree-view" value="default-dir-html" /> + <param name="default-leaf-view" value="default-rrd-html" /> + + <!-- Many of our RRDs have the field "bits" - let's define it here --> + <template name="bps"> + <leaf name="bps"> + <param name="comment" value="Bits per second" /> + <param name="leaf-type" value="rrd-def" /> + <param name="rrd-ds" value="bits" /> + <param name="rrd-cf" value="AVERAGE" /> + </leaf> + </template> + ... + <subtree name="Total"> + <param name="data-file" value="total.rrd" /> + <apply-template name="bps" /> + <leaf name="pps"> + <param name="comment" value="Packets per second" /> + <param name="leaf-type" value="rrd-def" /> + <param name="rrd-ds" value="pkts" /> + <param name="rrd-cf" value="AVERAGE" /> + </leaf> + <leaf name="packlen"> + <param name="comment" value="Average packet length in bytes" /> + <param name="leaf-type" value="rrd-cdef" /> + <param name="rpn-expr" value="bps,8,/,pps,/" /> + </leaf> + </subtree> + + +=head3 Aliases + +Alias is the alternative symbolic name for a subtree or a leaf. +It can be even a name from a different subtree hierarchy. +If that alternative hierarchy does not exist, the corresponding +subtrees are created: + + <subtree name="62.3.44.55"> + <alias>/Netflow/ExportersByName/rtrTelehouse1/</alias> + ... + +=head3 Compile-time variables + +Compile-time variables are those defined somewhere in datasource hierarchy, +and valid within a given subtree and its children. It is possible to define +pieces of XML configuration which are or are not compiled, depending on the +value of corresponding variable. + +Variables are set by C<setvar> XML element, with mandatory attributes +C<name> and C<value>. + +Variable values are used in C<iftrue> and C<iffalse> XML elements. +Mandatory parameter C<var> specifies the variable name. The child XML elements +are compiled if the variable value is true or false, correspondingly. +A true value is C<true> or a nonzero number. Undefined variable is identified +as false. + +Example: + + <template name="cisco-cbqos-classmap-meters"> + ... + <iftrue var="CiscoIOS_cbQoS::CMNoBufDrop"> + <leaf name="Dropped_No_Buffer"> + ... + </leaf> + </iftrue> + </template> + + <subtree name="QoS_Stats"> + <setvar name="CiscoIOS_cbQoS::CMNoBufDrop" value="true"/> + .... + </subtree> + + +=head3 Parameter value substitution + +For any given leaf, some parameters may reference the other parameter values, +by embracing the parameter name with percent signs: + + <param name="data-file" value="%snmp-host%_hostaverages.rrd" /> + +The parameter substitution is performed at runtime. The substitution formula +may be defined at a higher subtree level, and the substitution itself will +occur at leaf level. + +The parameter substitution is performed only to those paraneters +which are defined with the property "expand". + +=head3 Common parameters + +=over 4 + +=item * C<ds-type> + +Mandatory parameter for every datasource leaf. Currently, the following values +are recongized: + +=over 8 + +=item * C<rrd-file> + +The datasource is an RRD file generated by some external collector. +Implies mandatory parameters: C<data-dir>, C<data-file>, C<leaf-type>. + +=item * C<collector> + +The datasource is generated by Torrus Collector. +Implies mandatory parameters: C<collector-type>, C<storage-type>, +C<collector-period>, C<collector-timeoffset>. + +=item * C<rrd-multigraph> + +This leaf is dedicated to displaying of multiple +other datasources in one graph. It cannot be referenced for any +other purpose, because there's no numeric value associated with it. + +=back + +=item * C<nodeid> + +Optional. If defined, it should contain a unique string identifying +this particular leaf or subtree. + + +=item * C<node-display-name> + +Optional. If defined, it overrides the subtree or leaf name for displaying. +The subtree and leaf names are not allowed to have spaces and special +characters, and this parameter helps to display strings as they are, such as +router interface names. + + +=item * C<comment> + +Optional. This is a string of text which is displayed when browsing through +the tree. + +=item * C<help-text> + +Optional. This parameter is not inherited by child nodes. If defined, +the user is offered a I<Help> shortcut in the given subtree or view. +It allows to open a new window with the help text displayed, together with +the current path. Some simple markup is allowed in the text, in a format +of Template-Toolkit tool: +C<[%em('some text')%]> would be displayed in italics, and +C<[%strong('some text')%]> would be bold. + +=item * C<monitor> + +Optional. Comma-separated list of monitor names (spaces are allowed) that +must be run upon periodic runs of monitor module (see I<Monitor definitions> +section of this manual). Monitor schedule parameters must be defined +for the monitor to run properly: C<monitor-period> and C<monitor-timeoffset>. + +=item * C<monitor-period>, C<monitor-timeoffset> + +Mandatory parameters for leaves that have C<monitor> defined. +They define the monitor schedule for each individual datasource. +The time for execution is determined by formula: + + time + period - (time mod period) + timeoffset + +=item * C<monitor-vars> + +Required if one or more monitors requires the variables. In monitor's +RPN expressions, the variables are referenced as C<#varname>. These +variables are looked up in the leaf's C<monitor-vars> parameter. +The syntax of this parameter is semicolon-delimited C<name=value> pairs: + + <param name="monitor-vars" value="min=300000;max=1000000"/> + +=item * C<monitor-action-target> + +Optional. Specifies a reference to an alternative leaf which will be used +for the monitor action. For example, you might need to see a multigraph +leaf in the tokenset instead of one single datasource. + +=item * C<precedence> + +Optional. Default value: C<0>. When rendering, the subtree listing is +sorted according to precedence and alphabetic order of names. +The higher the precedence, the closer to the top of the list +the child node is displayed. + +=item * C<legend> + +Optional. If given, produces a short listing at the top of the HTML output, +with tabulated values. Format: C<Category1:Value1; Category2:Value2...>. +Spaces around the delimiters are ignored. + +Example: + + <subtree name="rtrZurich1"> + <param name="legend"> + Location:Zurich; + Contact: John Smith; + Telephone: 01 9911299 + </param> + +=item * C<graph-title> + +A horizontal string at the top of the graph. + +=item * C<graph-legend> + +Optional. This legend text is printed inside the graph explaining +the line color. + +=item * C<vertical-label> + +Optional. Text to print along Y axsis on the graph. + +=item * C<graph-lower-limit>, C<graph-upper-limit> + +Optional. Fix the upper and lower boundaries of the graph. + +=item * C<graph-rigid-boundaries> + +Optional. When set to "yes", the graph will not expand if the value is outside +the lower or upper limit. + +=item * C<rrd-scaling-base> + +Optional. Valid values are: "1000" and "1024". Default: "1000". +Determines the base for kilo-, mega-, and giga- scaling factor. +Normally it should be 1000 for traffic counters, and 1024 for memory +or storage sizes. + +=item * C<graph-logarithmic> + +Optional. When set to "yes", the graph is drawn in logarithmic y-axis scale. + +=item * C<line-style>, C<line-color> + +These optional parameters override the corresponding ones from the view +definition. + +=item * C<default-subtree-view>, C<default-leaf-view> + +Mandatory. Determine the default view for a leaf or subtree, correspondingly. +See I<View definitions> section of this manual. + +=item * C<rrgraph-views> + +Mandatory. Defines 5 views to display the graphs. Must contain 5 +comma-delimited view names for short-period, daily, weekly, monthly, +and yearly view. + +=item * C<tokenset-member> + +Optional. Adds this leaf or this subtree child leaves to the specified +token sets. Tokenset names are comma-separated, and must be defined in +C<E<lt>token-setsE<gt>> part of configuration. + +=item * C<descriptive-nickname> + +Optional. If defined, it is used in tokenset members listing as a member +identifier, instead of the leaf path. + +=item * C<hidden> + +Optional. Valid values: C<yes>, C<no>. +When set to C<yes>, the leaf or subtree is not +displayed in the subtree listing, +unless C<SHOWHIDDEN> option is true. When C<SHOWHIDDEN> is enabled, +the node name and comment are shown in italics. + +=item * C<has-overview-shortcuts>, C<overview-shortcuts>, +C<overview-subleave-name-X>, C<overview-shortcut-text-X>, +C<overview-shortcut-title-X>, C<overview-page-title-X>, +C<overview-direct-link-X>, C<overview-direct-link-view-X> + +When C<has-overview-shortcuts> is set to C<yes> on a subtree level, +default HTML templates expect the five parameters to be set. +C<overview-shortcuts> is a comma-separated list of shortcut names, +and for each name "X", C<overview-subleave-name-X> defines the +current subtree's grandchild leaves name which would compose the overview page. +When C<overview-direct-link-X> is set to C<yes>, the URL under the +graph will point to the direct child subtree, and +C<overview-direct-link-view-X> will define the view for that subtree. +Usually this view would be C<expanded-dir-html>. + +=item * C<ignore-lower-limit>, C<ignore-upper-limit>, C<ignore-limits> + +Optional. When set to C<yes>, they make the renderer ignore +C<graph-lower-limit>, C<graph-upper-limit>, or both, accordingly. +In addition, C<ignore-limits> disables the C<graph-rigid-boundaries> +parameter. + +=item * C<graph-ignore-decorations> + +Optional. When set to C<yes>, the view C<decorations> are ignored. + +=item * C<graph-disable-gprint> + +Optional. When set to C<yes>, the view parameter C<gprint-values> and other +GPRINT-related parameters are ignored. + +=item * C<hrule-legend-I<name>> + +Optional. If a horizontal rule with the given name is defined, this parameter +specifies the legend to be printed. + +=item * C<searchable> + +Optional. If set to C<yes>, the corresponding subtree or leaf is included +in the search database. + +=back + + +=head3 RRD-related parameters + +=over 4 + +=item * C<data-dir> + +Mandatory. Specifies the filesystem directory +path where the data files are resided. + +=item * C<data-file> + +Mandatory. Name of the data file. + +=item * C<leaf-type> + +Mandatory. Determines the type of RRD access. Recognized values are: + +=over 8 + +=item * C<rrd-def> + +Corresponds to DEF specification in RRDgraph query. Implies two mandatory +parameters: C<rrd-ds> and C<rrd-cf>, giving the DS name and consolidation +function, correspondingly. + +=item * C<rrd-ds> + +Mandatory when a leaf refers to an RRD file (C<storage-type=rrd> in +C<collector> leaves or C<leaf-type=rrd-def> in C<rrd-file> leaves). The +parameter Specifies the RRD datasource name within a file. + +=item * C<rrd-ds> + +Mandatory when a leaf refers to an RRD file (C<storage-type=rrd> in +C<collector> leaves or C<leaf-type=rrd-def> in C<rrd-file> leaves). The +parameter Specifies the RRD datasource name within a file. + +=item * C<rrd-cf> + +Mandatory under the same conditios as C<rrd-ds>. Defines the default +consolidation function which is used when retrieving the RRD data. + +=item * C<rrd-cdef> + +Supported for C<ds-type=rrd-file> only. +Corresponds to CDEF specification in RRDgraph query. Implies one +mandatory parameter: C<rpn-expr>, which gives the RPN expression. +Other leaves' value references are specified in curly braces. These leaves +can be specified as relative or absolute paths in the configuration tree. +See I<RPN expressions in Torrus> manual for more details. + +=back + +=item * C<rrd-hwpredict> + +Optional. If equals to C<enabled>, then this RRD datasource +is expected to have HWPREDICT and all the suite of +Holt-Winters consolidation functions. +In case of C<ds-type=collector>, C<rrd-hwpredict=enabled> indicates +that the RRD file must be created with use of Holt-Winters RRAs. + +=item * C<rrd-create-dstype> + +Mandatory when C<ds-type=collector> and C<storage-type=rrd>. +Specifies the datasource type for RRD creation. Valid values are: +C<GAUGE>, C<COUNTER>, C<DERIVE>, C<ABSOLUTE>. + +=item * C<rrd-create-rra> + +Mandatory when C<ds-type=collector> and C<storage-type=rrd>. +Space-separated list of RRA definitions for RRD creation, as they +are passed to RRD Create command. +Example: + + <!-- Round-robin arrays to be created, separated by space. + In this example, we keep 5-minute details for 2 weeks, + 30-minute average and maximum details for 6 weeks, + and 1-day aggregated stats for 2 years --> + <param name="rrd-create-rra"> + RRA:AVERAGE:0.5:1:4032 + RRA:AVERAGE:0.5:6:2016 RRA:MAX:0.5:6:2016 + RRA:AVERAGE:0.5:288:732 RRA:MAX:0.5:288:732 + </param> + +=item * C<rrd-create-heartbeat> + +Mandatory when C<ds-type=collector> and C<storage-type=rrd>. +Heartbeat parameter as defined in RRD Create manual page. + +=item * C<rrd-create-min>, C<rrd-create-max> + +Optional minimum and maximum parameters for RRD datasource. + +=item * C<rrd-create-hw-rralen> + +Mandatory when C<ds-type=collector> and C<storage-type=rrd> +and C<rrd-hwpredict=enabled>. Specifies the RRA length for +Holt-Winters archives. Recommended same length as main 5-minutes RRA. + +=item * C<rrd-create-hw-season>, C<rrd-create-hw-alpha>, + C<rrd-create-hw-beta>, C<rrd-create-hw-gamma>, + C<rrd-create-hw-winlen>, C<rrd-create-hw-failth> + +Optional Holt-Winters parameters. Default values are: + + season=288 + alpha=0.1, beta=0.0035, gamma=0.1, + window_length=9, failure_threshold=6 + +=back + +=head3 Collector-related parameters + +=over 4 + +=item * C<collector-type> + +Mandatory parameter for datasource type C<collector>. Currently supported +values are: C<snmp> and C<cdef>. Other valid values may be added with plugins. + +=item * C<storage-type> + +Mandatory parameter for datasource type C<collector>. Comma-separated list +of storage types. The collected value is duplicated on every storage listed. +Supported values are: C<rrd>, C<ext>. For C<ext> (external storage), +see the I<Reporting Setup Guide>. + +=item * C<collector-period>, C<collector-timeoffset> + +Mandatory parameters for datasource type C<collector>. +They define the collector schedule for each individual datasource. +The time for execution is determined by formula: + + time + period - (time mod period) + timeoffset + +=item * C<collector-dispersed-timeoffset> + +Optional. When set to C<yes>, C<compilexml> spreads the collector offsets +among values determined from C<collector-timeoffset-min>, +C<collector-timeoffset-max>, C<collector-timeoffset-step>, +and C<collector-timeoffset-hashstring>. + +=item * C<collector-timeoffset-min>, +C<collector-timeoffset-max>, C<collector-timeoffset-step> + +Mandatory when C<collector-dispersed-timeoffset> is set to C<yes>. +They define the limits and the step for collector timeoffset dispersion. + +=item * C<collector-timeoffset-hashstring> + +Mandatory when C<collector-dispersed-timeoffset> is set to C<yes>. +Defines the string that is used as a hash for timeoffset dispersion. + +=item * C<collector-instance-hashstring> + +Mandatory. +Defines the string that is used as a hash to calculate the collector +instance number for a particular leaf. +By default it is defined as C<%system-id%>, so that +the same collector instance deals with every remote system. + +=item * C<collector-instance> + +Mandatiry. The parameter defines the collector instance number. +This parameter is automatically calculated by the configuration compiler. + +=item * C<transform-value> + +Optional. Defines a piece of Perl code that will be used for value +transformation. The keyword C<DOLLAR> is replaced with the dollar sign ($), +and C<MOD> is replaced with the percent sign (%). +The initial value is supplied in C<$_>, which should be referenced as +C<DOLLAR_> in your Perl code. +The code should return a numeric value or C<U> for an undefined +value. The returned value is then passed to the storage. +The parameter substititions are performed on the value of the +parameter, therefore it should not contain the percent(%) and dollar ($) signs. + +=item * C<value-map> + +Optional. Collector may return values which need translation into +numbers. This parameter defines the mapping for such values. The +parameter value is a comma-separated list of C<value:number> pairs. + + +=item * C<collector-scale> + +Optional. Specifies the translation RPN formula for the data before +being passed to RRD database. Implicitly the datasource value is appended +to the left of the given RPN. I<Warning:> the translation works I<before> +the RRDtool processes the data, so it makes sence to scale only non-COUNTER +values. + +=item * C<snmp-ipversion> + +Mandatory for C<collector-type=snmp>. Valid values are C<4> and C<6>. The +parameter defines the IP protocol version. If C<snmp-host> contains a DNS +name, the IP address is determined by looking up A or AAAA DNS records, +according to IP version. + +=item * C<snmp-transport> + +Mandatory for C<collector-type=snmp>. Valid values are C<tcp> and C<udp>. + + +=item * C<snmp-host> + +Mandatory when C<collector-type=snmp>. Specifies the hostname or IP address +of the SNMP agent. + +=item * C<snmp-port> + +Mandatory when C<collector-type=snmp>. Specifies the UDP port of the +SNMP agent. + +=item * C<domain-name> + +Optional DNS domain name. If given, and if C<snmp-host> does not contain +dot symbol (.), this domain name is appended to C<snmp-host>. + +=item * C<snmp-localaddr> and C<snmp-localport> + +Optional parameters specifying the local socket binding address and port. + +=item * C<snmp-version> + +Mandatory when C<collector-type=snmp>. Specifies the SNMP version for the +given device. Valid values are: C<1>, C<2c>, C<3>. + +=item * C<snmp-community> + +Mandatory when C<collector-type=snmp> and SNMP version is +C<1> or C<2c>. Specifies the SNMP community for the given device. + +=item * C<snmp-username> + +Mandatory when C<collector-type=snmp> and SNMP version is C<3>. + +=item * C<snmp-authkey> + +Optional authentication key for SNMPv3. If not defined, the authentication +level is set to C<noAuthNoPriv>. If only C<snmp-authkey> or +C<snmp-authpassword> are specified, the security level is set to +C<authNoPriv>. The security level is set to C<authPriv> if either +of C<snmp-privkey> or C<snmp-privpassword> is defined. + +=item * C<snmp-authpassword> + +Optional authentication password for SNMPv3. See notes for C<snmp-authkey> +parameter. + +=item * C<snmp-authprotocol> + +Optional authentication protocol for SNMPv3. Valid values: C<md5> or C<sha>. +Default is C<md5>. + +=item * C<snmp-privkey> + +Optional privacy key for SNMPv3. If defined, C<snmp-authkey> or +C<snmp-authpassword> must be defined too. + +=item * C<snmp-privpassword> + +Optional privacy password for SNMPv3. If defined, C<snmp-authkey> or +C<snmp-authpassword> must be defined too. + +=item * C<snmp-privprotocol> + +Optional privacy protocol for SNMPv3. Valid values: C<des>, C<aes128cfb>, +or C<3desede>. Default is C<des>. + +=item * C<snmp-timeout> + +Mandatory when C<collector-type=snmp>. Specifies the SNMP session timeout +in seconds. + +=item * C<snmp-retries> + +Mandatory when C<collector-type=snmp>. Specifies the SNMP session retry count. + +=item * C<snmp-oids-per-pdu> + +Mandatory when C<collector-type=snmp>. Specifies the number of SNMP OIDs per +one UDP packet. + +=item * C<snmp-object> + +Mandatory when C<collector-type=snmp>. Specifies the SNMP OID to be polled +from the agent. The object must return a single numeric value. + +In order to reference the dynamic instances, i.e. interface counters, +two mapping types are supported: reverse mapping and variable value +substitution. + +Reverse mapping has syntax as follows: + + M(baseoid, string) + +The result of reverse mapping is the tail of the OID which has the head +C<baseoid> and whose value equals the string. + +Variable value substitution is defined by syntax: + + V(oid) + +The returned value must be a numeric value which is substituted in place +of this expression. + +=item * C<snmp-object-type> + +Optional. Supported values: C<COUNTER64>, C<OTHER>. When set to C<COUNTER64>, +the SNMP variable value is treated as 64-bit integer. Not using this +parameter may lead to loss of precision. + +=item * C<snmp-check-sysuptime> + +Optional. Default value: C<yes>. When set to C<no>, the collector does not +query C<SNMPv2-MIB::sysUpTime> (C<1.3.6.1.2.1.1.3.0>). By default, +the uptime counter is used to detect if the agent was rebooted between +the collector cycles. In this case the dynamic maps for the given host +are automatically rebuilt. This parameter is needed for compatibility +with some non-standard agents which don't implement this OID. + +=item * C<snmp-max-msg-size> + +Optional. If defined, it sets the SNMP maximum message size different from +default 1472 octets (true for UDP/IPv4, see Net::SNMP documentation for more +information). + +=item * C<snmp-ignore-mib-errors> + +Optional. If set to C<yes>, the SNMP errors C<noSuchObject>, C<noSuchInstance>, +C<endOfMibView> are ignored, and no action is performed when such errors +occur. + +=item * C<system-id> + +Mandatory for every collector type. +Default value for SNMP collector: C<%snmp-host%>. +Unique identifier of the host. +This parameter is used in various template definitions for +C<data-file>, C<descriptive-nickname> and C<collector-timeoffset-hashstring>. + +=item * C<rpn-expr> + +Mandatory when C<collector-type=cdef>. The RPN defines an arithmetic expression +that is used to create a new datasource from several other ones. For example, +it may define the sum of traffic on several different interfaces. + +=item * C<cdef-collector-delay> + +Mandatory when C<collector-type=cdef>. Defines the delay time in collector +periods. The collector will read the data from the RPN datasources with the +specified delay from the current time. F<cdef-collector-defs.xml> sets +the default value to 0. + +=item * C<cdef-collector-tolerance> + +Mandatory when C<collector-type=cdef>. Delay time in collector periods that +the collector accepts when no recent data is available. +F<cdef-collector-defs.xml> sets the default value to 2. + +=back + + +=head3 RRD-Multigraph leaves + +The leaves with C<ds-type=rrd-multigraph> are dedicated for +displaying of several datasource values in one graph. +Such leaves cannot be referenced for a numerical value, hence +cannot be monitored. + +Example: + + <subtree name="SampleMulti"> + <leaf name="sample1"> + <param name="ds-type" value="rrd-multigraph" /> + <param name="ds-names" value="in,out" /> + <param name="foobarpath" + value="/SNMP/Routers/213.230.38.4/FastEthernet0_0" /> + + <!-- parameter name tail is formed by the DS name --> + + <param name="ds-expr-in" value="{%foobarpath%/locIfInBitsSec}" /> + <param name="graph-legend-in" value="Bits per second in" /> + <param name="line-style-in" value="AREA" /> + <param name="line-color-in" value="#00FF00" /> + <param name="line-order-in" value="1" /> + + <param name="ds-expr-out" value="{%foobarpath%/locIfOutBitsSec}" /> + <param name="graph-legend-out" value="Bits per second out" /> + <param name="line-style-out" value="LINE2" /> + <param name="line-color-out" value="#0000FF" /> + <param name="line-order-out" value="2" /> + + </leaf> + </subtree> + +Parameters: + +=over 4 + +=item * C<ds-names> + +Comma-separated list of symbolic DS names. These names are +used for other DS-specific parameter names formation. +In the parameter descriptions below, C<X> stands for the DS name. + +=item * C<ds-expr-X> + +Datasource leaf RPN expression. +Any other parameter values may be substituted as C<%parameter_name%>. + +=item * C<graph-legend-X> + +Short description text used as the graph legend. + +=item * C<line-style-X> + +Line specification in RRD graph. May be I<C<LINE1>>, I<C<LINE2>> etc. +Two hashes in the beginning and a name refer to the line style from +the styling profile, e.g. C<##BpsIn>. + +=item * C<line-color-X> + +Line color. Must have the hash symbol in the beginning, like I<C<#0000FF>>. +Two hashes in the beginning and a name refer to the color from +the styling profile, e.g. C<##BpsIn>. + +=item * C<line-order-X> + +Numerical order of line drawing. The lines are drawn in accending order. +If omitted, the XML compiler issues warning, and Renderer conciders +the order of 100. + +=item * C<line-stack-X> + +Optional. When set to C<yes>, the line is stacked on top of a previous line. +Both areas and lines are stackable. + +=item * C<line-alpha-X> + +Optional. If specified, must be two hexademical, uppercase digits. This +parameter defines the line (or area) transparency. Value C<FF> is +equivalent to solid colour. Value C<7F> gives 50% transparency which should +be suitable for most applications. + +=item * C<ignore-views-X> + +Optional comma-separated list of view names. The graph for this DS name +will not be drawn in the views specified. The validator does not check +it, so it's up to you to guarantee that at least one DS is always displayed +in a multigraph. + +=item * C<disable-gprint-X> + +Optional. When set to C<yes>, this datasource is not included in GPRINT output. + +=back + +=head2 View definitions + +In our context, I<view> means any kind of object representation. +The same subtree or view can be displayed in different ways and in +different formats: HTML, graph image, plain text, etc. + +I<Renderer> module handles these view definitions. For any subtree +or leaf, it renders the specified view, and keeps the cache of rendered +files. + +Each subtree or leaf must have a default view. This is controlled by +two parameters that may be defined in the root subtree: +C<default-subtree-view> and C<default-leaf-view>. + +The set of views is flat, though they can inherit the parameters +one from another. Each view is referenced by its name, and is +defined by the set of parameters. Same way as with datasources, +certain parameter values imply the neccessaty to define certain other +parameters: + + <views> + <view name="default-rrgraph"> + <param name="view-type" value="rrgraph" /> + <param name="expires" value="300" /> + <param name="width" value="500" /> + <param name="height" value="250" /> + <param name="width-hint" value="580" /> + <param name="line-style" value="##SingleGraph" /> + <param name="line-color" value="##SingleGraph" /> + + <!-- Daily graph, inherits parameters from the above --> + <view name="last24h"> + <param name="start" value="-24h" /> + </view> + + <!-- Weekly graph --> + <view name="lastweek"> + <param name="start" value="-7d" /> + </view> + </view> + </views> + +Currently the view is defined by the configuration only. +Probably, in the future additional parameters will be supplied dynamically. + + +=head3 View parameters + +For every view, the mandatory parameters are: + +=over 4 + +=item * C<view-type> + +Determines the processing procedure which interprets the other parameters. + +=item * C<expires> + +Gives the expiration time in seconds for the I<Renderer> cache. + +=back + +The following values of C<view-type> are recognized: + +=over 4 + +=item * C<html> + +Defines the HTML representation of subtree or a leaf. +One additional parameter is required: C<html-template> must contain a file +name of the HTML template. Those templates are copied from F<templates> +subdirectory of the installation package. We use Template-Toolkit +E<lt>http://www.template-toolkit.orgE<gt> for HTML processing. +The template file name is defined with the parameter C<html-template>. + +The following +variables and functions are defined when the template is processed: + +=over 8 + +=item * C<token> + +Returns the current node token. + +=item * C<view> + +Returns the name of the current view. + +=item * C<path(token)> + +Returns the full path name of the given node token. + +=item * C<pathToken(path)> + +Returns the token for the specified path. + +=item * C<nodeExists(path)> + +Returns true if the specified path points to a node. + +=item * C<children(path)> + +Returns the list of children for the given path. + +=item * C<isLeaf(token)> + +Returns true if the token is pointing to a leaf node. + +=item * C<sortTokens(array)> + +Returns the array of tokens, sorted according to C<precedence> parameter. + +=item * C<nodeName(token)> + +Returns the node name part of the node path. + +=item * C<parent(token)> + +Returns the parent's token for the specified node. + +=item * C<nodeParam(token, param_name)> + +Returns the value of the parameter for the given node. + +=item * C<param(entity_name, param_name)> + +Returns the value of the parameter for the given view, monitor, or action. + +=item * C<url(token, [view])> + +Returns the URL which displays the given node using the given view. +If the view is omitted, use the default view. + +=item * C<persistentUrl(token, [view])> + +Same as above, but the URL is built from persistent information: nodeid +(if available) or full path in the tree. + +=item * C<splitUrls(token, [view])> + +Returns a piece of HTML code representing the path with clickable +node names, each referencing the corresponding view. + +=item * C<rrprint(token, view)> + +The specified view must be of type C<rrprint>. Returned is the text +output produced by this view. + +=item * C<scale(text)> + +Interprets the given text as a floating-point number and returns +its representation in the "metric" scale: 1000 is translated into "k", +million into "M" etc. It may be used together with C<rrprint> +for better formatting. + +=item * C<tsetMembers(tset)> + +Returns the array of the tokenset member tokens. + +=item * C<tsetList> + +Returns the array of the tokenset names. + +=item * C<stylesheet> + +Returns the relative URI to the default CSS stylesheet, +as defined in C<$Torrus::Renderer::stylesheet>. + +=item * C<version> + +Returns current Torrus package version. + +=back + +=item * C<rrgraph> + +Generates the RRD Graph representation of the given I<leaf> (remember, +subtrees are only logical grouping of the real data). + +The following parameters are mandatory for this kind of view: + +=over 8 + +=item * C<width>, C<height>, C<start> + +Correspond to same parameters in RRD Graph command. +C<end> can also be given, it defaults to I<C<now>>. + +=item * C<line-style> + +Line specification in RRD graph. May be I<C<LINE1>>, I<C<LINE2>> etc. +Two hashes in the beginning and a name refer to the line style from +the styling profile, e.g. C<##SingleGraph>. + +=item * C<line-color> + +Line color. Must have the hash symbol in the beginning, like I<C<#0000FF>>. +Two hashes in the beginning and a name refer to the color from +the styling profile, e.g. C<##SingleGraph>. + +=item * C<rrd-hwpredict> + +If equals to C<disabled>, HWPREDICT display is disabled for this view. +Note that if the datasource has C<rrd-hwpredict> parameter set to C<enabled>, +this emplies that the view would contain Holt-Winters boundaries and failures +graph. + +=item * C<hw-bndr-style> + +Optional parameter, defaults to C<LINE1>. Specifies the line style for +Holt-Winters boundaries. + +=item * C<hw-bndr-color> + +Optional parameter, defaults to C<#FF0000>. Specifies the color for +Holt-Winters boundaries. + +=item * C<hw-fail-color> + +Optional parameter, defaults to C<#FFFFA0>. Specifies the color for +Holt-Winters failure ticks. + +=item * C<hrules>, C<hrule-value-I<name>>, C<hrule-color-I<name>> + +Optional parameter C<hrules> contains a comma-separated list of +horizontal rule names. For each name, mandatory parameter +C<hrule-value-I<name>> defines a name of the leaf parameter that will be +used as the horizontal rule value. The rule is not drawn if such parameter +is not defined for the leaf. Mandatory parameter C<hrule-color-I<name>> +defines the color for the rule, of the form C<#DDDDDD>, where C<D> corresponds +to a hexademical digit. Two hashes in the beginning and a name refer to +the color from the styling profile, e.g. C<##HruleMin>. +Optional parameter C<hrule-legend-I<name>> +defines the legend text to be displayed on the graph. The following horizontal +rules are defined in F<defaults.xml> for all rrgraph views: + + <param name="hrules" value="min,norm,max"/> + <param name="hrule-color-min" value="##HruleMin"/> + <param name="hrule-value-min" value="lower-limit"/> + <param name="hrule-color-norm" value="##HruleNormal"/> + <param name="hrule-value-norm" value="normal-level"/> + <param name="hrule-color-max" value="##HruleMax"/> + <param name="hrule-value-max" value="upper-limit"/> + + +=item * C<decorations> + +Optional. Comma-separated list of decoration names. Decoration is an RRD +pseudo-line that does not depend on any datasource. For each decoration +name, the following parameters must be supplied: C<dec-order-E<lt>nameE<gt>> +determines the order of drawing. Negative order numbers correspond to +the lines or areas behind the data line. C<dec-expr-E<lt>nameE<gt>> +gives the RPN expression that defines the line or area. +C<dec-style-E<lt>nameE<gt>> and C<dec-color-E<lt>nameE<gt>> define +the style (AREA or LINE1..3) and the color of the drawing. +Node parameter C<graph-ignore-decorations> disables the decorations. + +=item * C<gprint-values>, C<gprint-header>, C<gprint-format-*> + +Optional. These parameters define the printing of values together with legends +below the graph. C<gprint-values> is a comma-separated list of format names, +and for each format name, there should be a corresponding C<gprint-format-*> +parameter. C<gprint-header> defines a string that will be printed on top of +all orther lines. Example: + + <param name="gprint-values" value="current,average,max,min"/> + <param name="gprint-header" + value="Current Average Maximum Minimum"/> + <param name="gprint-format-current" value="LAST:%8.2lf%s"/> + <param name="gprint-format-average" value="AVERAGE:%8.2lf%s"/> + <param name="gprint-format-max" value="MAX:%8.2lf%s"/> + <param name="gprint-format-min" value="MIN:%8.2lf%s"/> + +=item * C<description> + +Optional. Defines the text description of the graph. This description is +usually placed as ALT HTML attribute in the generated HTML pages. + +=item * C<rrd-params> + +Optional. Supplies additional RRDtool graph comand-line options, as one +string separated by spaces. + +=back + +=item * C<rrprint> + +This view produces the text output from PRINT statement in +RRD graph command. The required parameters are C<start> and C<print-cf>. +The first one defines the starting time. C<end> may be also optionally +specified. + +C<print-cf> specifies oe or more consolidation functions, separated by comma. +The result of the rendering is the text line with the output values +separated by colon (:). + +=back + +=item * C<disable-legend>, C<disable-title>, C<disable-vertical-label> + +When set to C<yes>, the corresponding elements of the graph are not displayed. + + + +=head3 Styling Profiles + +Styling profiles allow symbolic names to be used for line type +and color. + +Two hashes in the beginning and a name refer to the line style from +the styling profile, e.g. C<##BpsIn>, C<##green>, C<##one>, C<##two>. + + <leaf name="InOutBytes"> + <param name="comment" value="Input and Output bits per second graphs"/> + <param name="ds-type" value="rrd-multigraph"/> + <param name="ds-names" value="in,out"/> + <!-- IN --> + <param name="ds-expr-in" value="{ifInOctets}"/> + <param name="graph-legend-in" value="Bytes per second in"/> + <param name="line-style-in" value="##BpsIn"/> + <param name="line-color-in" value="##BpsIn"/> + <param name="line-order-in" value="1"/> + <!-- OUT --> + <param name="ds-expr-out" value="{ifOutOctets}"/> + <param name="graph-legend-out" value="Bytes per second out"/> + <param name="line-style-out" value="##BpsOut"/> + <param name="line-color-out" value="##BpsOut"/> + <param name="line-order-out" value="2"/> + </leaf> + +When processed the example above effectivly becomes: + + <leaf name="InOutBytes"> + <param name="comment" value="Input and Output bits per second graphs"/> + <param name="ds-type" value="rrd-multigraph"/> + <param name="ds-names" value="in,out"/> + <!-- IN --> + <param name="ds-expr-in" value="{ifInOctets}"/> + <param name="graph-legend-in" value="Bytes per second in"/> + <param name="line-style-in" value="AREA"/> + <param name="line-color-in" value="#00FF00"/> + <param name="line-order-in" value="1"/> + <!-- OUT --> + <param name="ds-expr-out" value="{ifOutOctets}"/> + <param name="graph-legend-out" value="Bytes per second out"/> + <param name="line-style-out" value="LINE2"/> + <param name="line-color-out" value="#0000FF"/> + <param name="line-order-out" value="2"/> + </leaf> + +Schema definitions can be modified in two ways +(see the I<Torrus Styling Profile Guide> manual for available styles +and override details) + +=over 4 + +=item * Create an overlay schema: + +Specify the overlay schema in torrus-siteconfig.pl using the +$Torrus::Renderer::stylingProfileOverlay variable. + +=item * Create a replacement schema: + +Specify the replacement schema in torrus-siteconfig using the +$Torrus::Renderer::stylingProfile variable. + +=back + + +=head2 Token sets definitions + +I<Token> is a symbolic identifier for each subtree or a leaf. + +A I<tokenset> is a named list of tokens. Its contents can be +rendered, and its members can be added or removed at any time. + +Each tokenset can have a number of parameters defined. It also +inherits the parameter defined in the top C<E<lt>token-setsE<gt>> +XML element: + + <token-sets> + + <param name="default-tset-view" value="default-tset-html" /> + <param name="default-tsetlist-view" value="tset-list-html" /> + + <token-set name="jumps"> + <param name="comment" value="Traffic rate jumps" /> + </token-set> + + <token-set name="hw-failures"> + <param name="comment" value="Holt-Winters prediction failures" /> + </token-set> + + </token-sets> + +Parameter C<default-tsetlist-view> is mandatory for tokenset list. +It defines the default view when displaying the list of tokensets. + +The following parameters are mandatory for tokensets: + +=over 4 + +=item * C<default-tset-view> + +Determines the view for displaying the tokenset contents. + +=item * C<comment> + +The text that describes this tokenset. + +=back + +=head2 Monitor definitions + +I<Monitor> is a named set of parameters that defines the behaviour +of monitor module. Each leaf can be given a number of monitors +via C<monitor> parameter. + +Upon monitor module run, an I<action> is launched if the alarm conditions +of a given monitor are satisfied. + + <monitors> + <!-- First define the actions --> + + <!-- This action will put the graphs of alarmed datasources in + a single alarm report page --> + <action name="graph-hw-failures"> + <param name="action-type" value="tset" /> + <param name="set-name" value="hw-failures" /> + </action> + + <action name="graph-jumps"> + <param name="action-type" value="tset" /> + <param name="set-name" value="jumps" /> + </action> + + <monitor name="hw-failures"> + <param name="monitor-type" value="failures" /> + <param name="action" value="graph-hw-failures" /> + <param name="expires" value="3600" /> + </monitor> + + <!-- alarm if 5 minutes away it was 10 times lower --> + <monitor name="high-jumps"> + <param name="monitor-type" value="expression" /> + <param name="rpn-expr" value="{(-300)},10,*,GT,{},{(-300)},10,/,LT,OR" /> + <param name="action" value="graph-jumps" /> + <param name="expires" value="3600" /> + <param name="comment" + value="Value jumped more than 10-fold in 5 minutes" /> + </monitor> + + <monitor name="hundred-megs"> + <param name="monitor-type" value="expression" /> + <param name="rpn-expr" value="100,1024,1024,*,*,GT" /> + <param name="action" value="graph-jumps" /> + <param name="expires" value="3600" /> + <param name="comment" + value="Traffic is higher than 10 mbps" /> + </monitor> + </monitors> + +=head3 Event types + +Should the alarm condition occur, a series of events is happening +in sequentional order: + +=over 4 + +=item * C<set> + +This event type occurs the first time the alarm condition is met. + +=item * C<repeat> + +This event type means that the alarm condition still persists +after the previous run of Monitor. + +=item * C<clear> + +Event of this type happens when the alarm condition stops. + +=item * C<forget> + +Once the alarm is cleared, this event happens after the expiration +time of the monitor. + +=back + +=head3 Monitor parameters + +=over 4 + +=item * C<monitor-type> + +Mandatory parameter. Specifies the monitor type. The following monitor +types are recognized: + +=over 8 + +=item * C<failures> + +Triggers the action when Holt-Winters FAILURES function gives value of 1. +This requires RRDtool verion 1.1.x and aberrant behaviour parameters +defined for te given RRD file. + +=item * C<expression> + +Triggers the action when given RPN expression returns nonzero. +See I<RPN expressions in Torrus> manual for more details. +This monitor type implies that the RPN expression is specified in +C<rpn-expr> parameter. The current leaf value is prepended to the given RPN. + +=back + +=item * C<rpn-expr> + +Mandatory for monitor type C<expression>. Defines the RPN expression to +evaluate. The current leaf value is prepended to the given RPN. +The expresion may reference leaf-dependent variables: the +constructs of the form C<#varname> are replaced with the variable +value specified in the leaf's C<monitor-vars> parameter. + +=item * C<action> + +Mandatory parameter, comma-separated list of action names (spaces +are allowed). Each action is triggered when the alarm condition is met. + +=item * C<expires> + +Mandatory parameter, the number of seconds of expiration period. +After the alarm condition becomes false, this parameter determines +the time of memorizing the event in monitor status reports. + +=item * C<comment> + +Optional but recommended parameter, specifies the string identifying +the event that this monitor watches. + +=item * C<severity> + +Optional severity level. Used for the action type C<exec>. + +=item * C<display-rpn-expr> + +Optional RPN expression for transforming the datasource value. +If defined, it will be applied to the value before setting +C<TORRUS_VALUE> and C<TORRUS_DISPLAY_VALUE> environment variables. + +=item * C<display-format> + +Optional I<sprintf> format for displaying the value in +C<TORRUS_DISPLAY_VALUE> environment variable. Default is C<%.2f>. + +=back + + +=head3 Action parameters + +=over 4 + +=item * C<action-type> + +Mandatory parameter, defines the type of action. Recognized +values are: + +=over 8 + +=item * C<tset> + +When this type of action is triggered, the leaf is added to the specified +tokenset (see I<Token sets definitions> section in this manual). +The leaf persists in the tokenset until the event of type C<forget>. +This action type implies the parameter C<tset-name>. + +=item * C<exec> + +This action type defines an external program to launch. Two other parameters +determinate its behaviour: mandatory C<command> and optional C<launch-when>. + +=back + +=item * C<tset-name> + +Mandatory for action type C<tset>. Defines the tokenset name +where the leaf is added when the monitor condition is met. + +=item * C<command> + +Mandatory for action type C<exec>. Defines the external program to launch. +The following strings are substituted in the parameter value: + +=over 8 + +=item * C<E<amp>gt;> + +Relaced with C<E<gt>>. + +=item * C<E<amp>lt;> + +Relaced with C<E<lt>>. + +=back + +The following environment variables are passed to the child process: + +=over 8 + +=item * C<$TORRUS_HOME> + +C<prefix> where Torrus was installed. + +=item * C<$TORRUS_BIN> + +Directory containing Torrus executables. + +=item * C<$TORRUS_UPTIME> + +Number of seconds since Monitor has started. + +=item * C<$TORRUS_TREE>, C<$TORRUS_TOKEN>, C<$TORRUS_NODEPATH> + +Tree name, token and pathname of the leaf causing the alarm. + +=item * C<$TORRUS_NCOMMENT>, C<$TORRUS_NPCOMMENT> + +C<comment> parameter of the node and its parent. +Empty if the parameter is not defined for the given leaf. + +=item * C<$TORRUS_EVENT> + +Event type. + +=item * C<$TORRUS_MONITOR> + +Monitor name + +=item * C<$TORRUS_MCOMMENT> + +Monitor's C<comment> parameter value. + +=item * C<$TORRUS_TSTAMP> + +Timestamp (in seconds since Epoch) of the event. + +=item * C<$TORRUS_VALUE> + +For expression monitor type, this returns the last read value of the +datasource, possibly transformed by C<display-rpn-expr> expression. + +=item * C<$TORRUS_DISPLAY_VALUE> + +For expression monitor type, it contains a human-readable form +of the value, possibly transformed by C<display-rpn-expr> expression. + +=item * C<$TORRUS_SEVERITY> + +If the C<severity> parameter is defined in the monitor, its value +is passed with this variable. + +=back + +=item * C<launch-when> + +Optional for action type C<exec>. The comma-separated list of event +types when the given action should be launched. If not defined, +the event type C<set> is used by default. + +=item * C<setenv-params> + +Optional for action type C<exec>. The comma-separated list of leaf parameters +which would be passed as environment variables to the child process. +The environment variables are of the form C<$TORRUS_P_paramname>. Hyphens ('-') +are replaced with underscores ('_') in the parameter names. + +=item * C<setenv-dataexpr> + +Optional for action type C<exec>. Comma-separated list of C<ENV=paramname> +pairs. C<ENV> defines the environment variable name: it is prefixed with +C<Torrus_>. C<paramname> defines the action parameter name. This parameter +is interpreted as RPN expression applied to the current leaf being monitored. +The result of this RPN expression is passed to the action script +in the environment variable. + +Example: + + <action name="report-temperature"> + <param name="action-type" value="exec" /> + + <!-- This is our proprietary reporting script --> + <param name="command"> + /usr/local/bin/report_temperature + </param> + <param name="launch-when" value="set" /> + + <!-- We want to tell the action script the actual values + of the "temperature" and "humidity" leaves in the current + datasource tree --> + <param name="setenv-dataexpr" value="TEMP=expr-temp, HMD=expr-hmd" /> + <param name="expr-temp" value="{temperature(LAST)}" /> + <param name="expr-hmd" value="{humidity(LAST)}" /> + + <!-- We also want to tell the action script the parameter "monitor-vars" + which was configured for the current leaf. --> + <param name="setenv-params" value="monitor-vars" /> + </action> + + +=back + + +=head1 Author + +Copyright (c) 2002-2005 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt> |