From 6d76289fd16d8d25a11ef90ed43c49978c4b66a1 Mon Sep 17 00:00:00 2001 From: Johanna England Date: Fri, 1 Mar 2024 12:02:29 +0100 Subject: [PATCH 1/8] Don't create coverage dir for docs environment This resulted in a warning and would fail in tox 4 --- tox.ini | 1 + 1 file changed, 1 insertion(+) diff --git a/tox.ini b/tox.ini index e20f271966..a5e7e62de8 100644 --- a/tox.ini +++ b/tox.ini @@ -128,6 +128,7 @@ setenv = LANG=C.UTF-8 VIRTUALENV_PIP=23.1.0 allowlist_externals = sh +commands_pre = commands = sphinx-build doc/ doc/_build/ sh -c "cd doc; python -c 'import conf; print(conf.version)' > {toxinidir}/reports/doc_version" From a21c6b2b2910b1aaf035387f8a96711045a4b67a Mon Sep 17 00:00:00 2001 From: Johanna England Date: Fri, 1 Mar 2024 13:13:57 +0100 Subject: [PATCH 2/8] Fix formatting in docstring --- python/nav/mibs/mibretriever.py | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/python/nav/mibs/mibretriever.py b/python/nav/mibs/mibretriever.py index fb6b04b48d..be0312f45c 100644 --- a/python/nav/mibs/mibretriever.py +++ b/python/nav/mibs/mibretriever.py @@ -219,15 +219,13 @@ class MibTableResultRow(dict): Acts as a dictionary. The row index is available through the integer key 0, or as the member attribute 'index'. - """ def __init__(self, index, columns=None): """Initialize with the row index of this row. - index -- index OID - columns -- optional list of column names to pre-allocate with - None values. + :param index: index OID + :param columns: optional list of column names to pre-allocate with None values. """ if columns is None: From d910cc35b1363359a63005d6eaafba1ad5225f03 Mon Sep 17 00:00:00 2001 From: Johanna England Date: Fri, 1 Mar 2024 13:14:08 +0100 Subject: [PATCH 3/8] Update link --- doc/hacking/adding-environment-probe-support.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/hacking/adding-environment-probe-support.rst b/doc/hacking/adding-environment-probe-support.rst index c70658b936..170814bd75 100644 --- a/doc/hacking/adding-environment-probe-support.rst +++ b/doc/hacking/adding-environment-probe-support.rst @@ -391,6 +391,6 @@ temperature sensors of this device into NAV's database. The :program:`ipdevpoll` ``1minstats`` job will retrieve the sensor readings once every minute and send them to Graphite. -.. _sensorProbe8: http://www.akcpinc.com/products/base-units/sensorProbe-Series/sensorProbe8/ +.. _sensorProbe8: https://www.akcp.com/akcp-products/sensorprobe-series/sensorprobe8/ .. _Twisted: https://twistedmatrix.com/ .. _Deferred: http://twistedmatrix.com/documents/current/api/twisted.internet.defer.Deferred.html From b502dad81952ed5b188d031b7a97dab8c87cb1db Mon Sep 17 00:00:00 2001 From: Johanna England Date: Fri, 1 Mar 2024 13:28:01 +0100 Subject: [PATCH 4/8] Remove `document isn't included in any toctree` warnings --- doc/faq/faq.rst | 5 +++++ doc/hacking/adding-environment-probe-support.rst | 6 ++++++ doc/reference/index.rst | 2 ++ 3 files changed, 13 insertions(+) diff --git a/doc/faq/faq.rst b/doc/faq/faq.rst index a93a7c08ce..70f9e2fab9 100644 --- a/doc/faq/faq.rst +++ b/doc/faq/faq.rst @@ -140,3 +140,8 @@ example:: * 6 * * * navclean --force --arp --cam --interval '6 months' See the output of ``navclean --help`` for usage details. + +.. toctree:: + :hidden: + + /faq/graph_gaps \ No newline at end of file diff --git a/doc/hacking/adding-environment-probe-support.rst b/doc/hacking/adding-environment-probe-support.rst index 170814bd75..0f7edc50d2 100644 --- a/doc/hacking/adding-environment-probe-support.rst +++ b/doc/hacking/adding-environment-probe-support.rst @@ -391,6 +391,12 @@ temperature sensors of this device into NAV's database. The :program:`ipdevpoll` ``1minstats`` job will retrieve the sensor readings once every minute and send them to Graphite. +.. toctree:: + :hidden: + + /api/sensor + /api/mibretriever + .. _sensorProbe8: https://www.akcp.com/akcp-products/sensorprobe-series/sensorprobe8/ .. _Twisted: https://twistedmatrix.com/ .. _Deferred: http://twistedmatrix.com/documents/current/api/twisted.internet.defer.Deferred.html diff --git a/doc/reference/index.rst b/doc/reference/index.rst index ccd12265b0..ad88ec27e6 100644 --- a/doc/reference/index.rst +++ b/doc/reference/index.rst @@ -21,6 +21,8 @@ This section contains reference material for end-users. ipdevpoll external_authentication mailin + models-event + models-manage navstats portadmin radius From 7b7bc5664fb1f0bf1cb2c57577998b2412286600 Mon Sep 17 00:00:00 2001 From: Johanna England Date: Fri, 1 Mar 2024 13:45:08 +0100 Subject: [PATCH 5/8] Use program output from `ipdevpolld --help` instead of copy paste --- doc/reference/ipdevpoll.rst | 36 +----------------------------------- 1 file changed, 1 insertion(+), 35 deletions(-) diff --git a/doc/reference/ipdevpoll.rst b/doc/reference/ipdevpoll.rst index 215de17198..64f20d5a12 100644 --- a/doc/reference/ipdevpoll.rst +++ b/doc/reference/ipdevpoll.rst @@ -9,41 +9,7 @@ intervals. These jobs are fully user-configurable. Usage ===== -:: - - usage: ipdevpolld [-h] [--version] [-f] [-s] [-j] [-p] [-J JOBNAME] - [-n NETBOX] [-m [WORKERS]] [-M JOBS] [-P] [--capture-vars] - [-c] [--threadpoolsize COUNT] [--worker] - - optional arguments: - -h, --help show this help message and exit - --version show program's version number and exit - -f, --foreground run in foreground instead of daemonizing - -s, --log-stderr log to stderr instead of log file - -j, --list-jobs print a list of configured jobs and exit - -p, --list-plugins load and print a list of configured plugins - -J JOBNAME run only JOBNAME jobs in this process - -n NETBOX, --netbox NETBOX - Run JOBNAME once for NETBOX. Also implies -f and -s - options. - -m [WORKERS], --multiprocess [WORKERS] - Run ipdevpoll in a multiprocess setup. If WORKERS is - not set it will default to number of cpus in the - system - -M JOBS, --max-jobs-per-worker JOBS - Restart worker processes after completing JOBS jobs. - (Default: Don't restart) - -P, --pidlog Include process ID in every log line - --capture-vars Capture and print locals and globals in tracebacks - when debug logging - -c, --clean cleans/purges old job log entries from the database - and then exits - --threadpoolsize COUNT - the number of database worker threads, and thus db - connections, to use in this process - --worker Used internally when lauching worker processes - - This program runs SNMP polling jobs for IP devices monitored by NAV +.. program-output:: ipdevpolld --help Manually running a job for a given netbox ----------------------------------------- From bf383cf4ceda2d47e8b2d960fd866792fe5b8940 Mon Sep 17 00:00:00 2001 From: Johanna England Date: Fri, 1 Mar 2024 14:01:35 +0100 Subject: [PATCH 6/8] Remove unknown option --- NOTES.rst | 4 ++-- doc/reference/ipdevpoll.rst | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/NOTES.rst b/NOTES.rst index 62223935e9..c356b9d6cd 100644 --- a/NOTES.rst +++ b/NOTES.rst @@ -562,7 +562,7 @@ Daemon startup privileges By accident, some of NAV's daemons have been running as the privileged ``root`` user since NAV 4.9.0, due to changes in the process control system. NAV 5.0.4 -introduces the :option:`privileged` option in the :file:`daemons.yml` configuration +introduces the ``privileged`` option in the :file:`daemons.yml` configuration file, to signal which daemons actually need to be started with root privileges. Only :program:`snmptrapd` and :program:`pping` need root privileges on startup, @@ -573,7 +573,7 @@ Please ensure your :file:`daemon.yml` configuration file is updated. Also, be aware that after upgrading to NAV 5.0.4 from any version from 4.9.0 and up, you may have some NAV log files that are owned by ``root``, which will cause some of the daemons to fail on startup. Please ensure all NAV log files are writable -for the user defined as :option:`NAV_USER` in :file:`nav.conf`. +for the user defined as ``NAV_USER`` in :file:`nav.conf`. New features diff --git a/doc/reference/ipdevpoll.rst b/doc/reference/ipdevpoll.rst index 64f20d5a12..4b36aa9d85 100644 --- a/doc/reference/ipdevpoll.rst +++ b/doc/reference/ipdevpoll.rst @@ -135,7 +135,7 @@ are reserved for synchronous communication with the PostgreSQL database backend. Even on a multi-core server, this means all of ipdevpoll's work is limited to a single core. Once ipdevpoll's workload grows beyond what a single core can handle, ipdevpoll can optionally run in a *multiprocess mode*, using -the :option:`--multiprocess` option. +the ``--multiprocess`` option. In multiprocess mode, ipdevpoll spawns a number of worker processes, while the master process becomes a simple job scheduler, distributing the actual jobs to @@ -145,7 +145,7 @@ the individual workers. ipdevpoll's default number of workers processes and threads aren't necessarily sane for multiprocess usage. Unless a number of workers is - supplied to the :option:`--multiprocess` option, it will spawn a number of + supplied to the ``--multiprocess`` option, it will spawn a number of workers corresponding to the number of cores it detects on your system. The default number of database threads in ipdevpoll's threadpool is **10** per process, which means each worker process will create **10 individual connections to @@ -155,13 +155,13 @@ the individual workers. default pool of 100 available connections, causing other NAV processes to be unable to connect to the database. When enabling multiprocess mode, you should really tune down the threadpool size by adding the - :option:`--threadpoolsize` option. + ``--threadpoolsize`` option. Another good thing about the multiprocess mode is that you can limit the number of jobs any worker process will run before it is killed and respawned. This may provide additional protection against unintended resource leaks. See -the :option:`--max-jobs-per-worker` option. +the ``--max-jobs-per-worker`` option. You can make sure ipdevpoll always runs in multiprocess mode by altering the ``command`` option in the ``ipdevpoll`` entry of the configuration file From a4a1de4570b9132f10345d1c48cb8058000e0b4c Mon Sep 17 00:00:00 2001 From: Johanna England Date: Fri, 1 Mar 2024 15:56:26 +0100 Subject: [PATCH 7/8] Remove table for event types without alert types --- doc/reference/alerttypes.rst | 20 -------------------- 1 file changed, 20 deletions(-) diff --git a/doc/reference/alerttypes.rst b/doc/reference/alerttypes.rst index 2a7419cf9e..bb3cbe0c8f 100644 --- a/doc/reference/alerttypes.rst +++ b/doc/reference/alerttypes.rst @@ -109,13 +109,6 @@ Tells us whether the load has passed a certain threshold. ------------------ Tells us whether a link is up or down. -.. list-table:: Alerts associated with linkState events - :widths: 25 75 - :header-rows: 1 - - * - Alert type name - - Description - @@ -161,13 +154,6 @@ Basic information --------------------- Notification event, typically between NAV systems -.. list-table:: Alerts associated with notification events - :widths: 25 75 - :header-rows: 1 - - * - Alert type name - - Description - @@ -175,12 +161,6 @@ Notification event, typically between NAV systems --------------------- Lifetime event for a device -.. list-table:: Alerts associated with deviceActive events - :widths: 25 75 - :header-rows: 1 - - * - Alert type name - - Description From 00a96e9345d15a23ea6e416711a457409c370a7f Mon Sep 17 00:00:00 2001 From: Johanna England Date: Mon, 4 Mar 2024 11:37:34 +0100 Subject: [PATCH 8/8] Generate alert type docs from database --- doc/reference/alerttypes.rst | 213 ++++++++++++++++++++++++++++++++++- 1 file changed, 210 insertions(+), 3 deletions(-) diff --git a/doc/reference/alerttypes.rst b/doc/reference/alerttypes.rst index bb3cbe0c8f..2f77fd945f 100644 --- a/doc/reference/alerttypes.rst +++ b/doc/reference/alerttypes.rst @@ -109,6 +109,17 @@ Tells us whether the load has passed a certain threshold. ------------------ Tells us whether a link is up or down. +.. list-table:: Alerts associated with linkState events + :widths: 25 75 + :header-rows: 1 + + * - Alert type name + - Description + * - ``linkUp`` + - Link active + * - ``linkDown`` + - Link inactive + @@ -154,6 +165,13 @@ Basic information --------------------- Notification event, typically between NAV systems +.. list-table:: Alerts associated with notification events + :widths: 25 75 + :header-rows: 1 + + * - Alert type name + - Description + @@ -161,6 +179,12 @@ Notification event, typically between NAV systems --------------------- Lifetime event for a device +.. list-table:: Alerts associated with deviceActive events + :widths: 25 75 + :header-rows: 1 + + * - Alert type name + - Description @@ -176,13 +200,13 @@ Registers the state of a device * - Alert type name - Description * - ``deviceInIPOperation`` - - The device is now in operation with an active IP address. + - The device is now in operation with an active IP address * - ``deviceInStack`` - - The device is now in operation as a chassis module. + - The device is now in operation as a chassis module * - ``deviceRMA`` - RMA event for device. * - ``deviceNewModule`` - - The device has been found as a module. + - The device has been found as a module. * - ``deviceNewChassis`` - The device has been found as a chassis. * - ``deviceNewPsu`` @@ -192,6 +216,7 @@ Registers the state of a device + *deviceNotice* events --------------------- Registers a notice on a device @@ -360,3 +385,185 @@ The state of this BGP peering session changed +*juniperYellowAlarmState* events +-------------------------------- +Tells us if a Juniper device has any open yellow alarms. + +.. list-table:: Alerts associated with juniperYellowAlarmState events + :widths: 25 75 + :header-rows: 1 + + * - Alert type name + - Description + * - ``juniperYellowAlarmOn`` + - The Juniper device has some yellow alarms. + * - ``juniperYellowAlarmOff`` + - The Juniper device has no yellow alarms. + + + + +*juniperRedAlarmState* events +----------------------------- +Tells us if a Juniper device has any open red alarms. + +.. list-table:: Alerts associated with juniperRedAlarmState events + :widths: 25 75 + :header-rows: 1 + + * - Alert type name + - Description + * - ``juniperRedAlarmOn`` + - The Juniper device has some red alarms. + * - ``juniperRedAlarmOff`` + - The Juniper device has no red alarms. + + + + +*weathergoose_temperature* events +--------------------------------- + + +.. list-table:: Alerts associated with weathergoose_temperature events + :widths: 25 75 + :header-rows: 1 + + * - Alert type name + - Description + * - ``cmClimateTempCTRAP`` + - Climate Temperature Sensor Trap + * - ``cmClimateTempCCLEAR`` + - Climate Temperature Sensor Clear Trap + * - ``cmClimateTempCNOTIFY`` + - Climate Temperature Sensor Trap + * - ``cmTempSensorTempCNOTIFY`` + - Remote Temp Sensor - Temperature Trap + * - ``cmTempSensorTempCCLEAR`` + - Remote Temp Sensor - Temperature Clear Trap + * - ``gstClimateTempCNOTIFY`` + - Climate Temperature Sensor Trap + * - ``gstTempSensorTempCNOTIFY`` + - Remote Temp Sensor - Temperature Trap + * - ``gstClimateTempCCLEAR`` + - Climate Temperature Sensor Clear Trap + * - ``gstTempSensorTempCCLEAR`` + - Remote Temp Sensor - Temperature Clear Trap + + + + +*weathergoose_humidity* events +------------------------------ + + +.. list-table:: Alerts associated with weathergoose_humidity events + :widths: 25 75 + :header-rows: 1 + + * - Alert type name + - Description + * - ``cmClimateHumidityTRAP`` + - Climate Humidity Sensor Trap + * - ``cmClimateHumidityCLEAR`` + - Climate Humidity Sensor Clear Trap + * - ``cmClimateHumidityNOTIFY`` + - Climate Humidity Sensor Trap + * - ``gstClimateHumidityNOTIFY`` + - Climate Humidity Sensor Trap + * - ``gstClimateHumidityCLEAR`` + - Climate Humidity Sensor Clear Trap + + + + +*weathergoose_airflow* events +----------------------------- + + +.. list-table:: Alerts associated with weathergoose_airflow events + :widths: 25 75 + :header-rows: 1 + + * - Alert type name + - Description + * - ``cmClimateAirflowTRAP`` + - Climate Air Flow Sensor Trap + * - ``cmClimateAirflowCLEAR`` + - Climate Air Flow Sensor Clear Trap + * - ``cmClimateAirflowNOTIFY`` + - Climate Air Flow Sensor Trap + * - ``gstClimateAirflowNOTIFY`` + - Climate Air Flow Sensor Trap + * - ``gstClimateAirflowCLEAR`` + - Climate Air Flow Sensor Clear Trap + + + + +*weathergoose_light* events +--------------------------- + + +.. list-table:: Alerts associated with weathergoose_light events + :widths: 25 75 + :header-rows: 1 + + * - Alert type name + - Description + * - ``cmClimateLightTRAP`` + - Climate Light Sensor Trap + * - ``cmClimateLightCLEAR`` + - Climate Light Sensor Clear Trap + * - ``cmClimateLightNOTIFY`` + - Climate Light Sensor Trap + * - ``gstClimateLightNOTIFY`` + - Climate Light Sensor Trap + * - ``gstClimateLightCLEAR`` + - Climate Light Sensor Clear Trap + + + + +*weathergoose_sound* events +--------------------------- + + +.. list-table:: Alerts associated with weathergoose_sound events + :widths: 25 75 + :header-rows: 1 + + * - Alert type name + - Description + * - ``cmClimateSoundTRAP`` + - Climate Sound Sensor Trap + * - ``cmClimateSoundCLEAR`` + - Climate Sound Sensor Clear Trap + * - ``cmClimateSoundNOTIFY`` + - Climate Sound Sensor Trap + * - ``gstClimateSoundNOTIFY`` + - Climate Sound Sensor Trap + * - ``gstClimateSoundCLEAR`` + - Climate Sound Sensor Clear Trap + + + + +*upsPowerState* events +---------------------- +UPS running on battery or utility power + +.. list-table:: Alerts associated with upsPowerState events + :widths: 25 75 + :header-rows: 1 + + * - Alert type name + - Description + * - ``upsOnBatteryPower`` + - Ups running on battery power + * - ``upsOnUtilityPower`` + - Ups running on utility power + + + +