This is the modern Python re-implementation of the battle-proven Zino network state monitor, first implemented in Tcl/Scotty at Uninett in the 1990s.
This is still a work in progress, and is not yet a fully functional replacement for the original Tcl-based Zino. An incomplete list of features that have yet to be ported:
- No support for reading trap messages from a trap multiplexer like
straps
/nmtrapd
.
Development of Zino 2.0 is fully sponsored by NORDUnet, on behalf of the nordic NRENs.
Zino Is Not OpenView.
Zino is an SNMP network monitor that began its life at Uninett in the mid 1990s. It was a homegrown system written in Tcl, specifically to monitor the routers of the Norwegian national research network (NREN), a large backbone network that connects the widely geographically dispersed higher education and research institutions of Norway. Uninett was also part of NORDUnet, the collaboration that interconnects the NRENs of the Nordic countries, and Zino is also utilized to monitor the NORDUnet backbone.
Here's a quote about its features from the README
file of the original Tcl
codebase:
o Trap-driven polling; receives and interprets traps.
o Periodic status polling (by default low frequency).
o A simplistic event handling system.
o A simple SMTP-like client/server protocol.
o A TK-based user interface.
all in a little under 5000 lines of Tcl.
This project aims to port all this to Python, except for the TK-based user interface. The Python implementation keeps backwards compatibility with the "simple SMTP-like client/server protocol", so that the existing user interface clients can be re-used (such as Ritz and cuRitz). Additionally, a new web user interface client is being developed at https://github.com/uninett/howitz .
Zino is essentially a small program that can run in the background, monitoring your router network for:
- Link state
- BGP session state
- BFD session state
- Juniper chassis alarms
All changes will result in an "event" (aka a "case"), in which Zino will log all further related changes until the case is manually closed by a human operator via the server protocol on port 8001 (essentially through some user interface).
Notifications are typically achieved by having a client program to fetch active events from the Zino server and decide from that which notifications need to be sent.
Zino has very few dependencies, other than the Python packages required to run it. Zino serializes its running state to a JSON file on disk, and can resume its work from this file when restarted.
Redundancy can thus be achieved by running two or more Zino servers in parallel. A typical solution is for one server to be the "master", and the other to be a "hot standby". To ensure the master and the standby are mostly in sync, a typical solution is to transfer the state dump from the master to the standby every 24 hours and then restarting the standby from the master's state dump. Zino clients can be typically be configured to automatically switch to using a standby server if the master is unavailable.
First, ensure you have Python 3.9, 3.10 or 3.11 available on your system. Second, we recommend creating a Python virtual environment, which is isolated from other Python software installed on your system, and installing Zino into that.
To create a new virtual environment in the directory ./zino-env
, run:
python -m venv ./zino-env
This virtual environment can now be "activated" in your shell, so that any further Python related commands that are run in your shell are running from inside the new environment:
. ./zino-env/bin/activate
With your Zino virtual environment activated in your shell, run:
pip install zino
With your Zino virtual environment activated in your shell, clone the Zino source code directly from GitHub and install it from there:
git clone https://github.com/Uninett/zino.git
cd zino
pip install .
In order for Zino to function properly, you first need to make a minimal
polldevs.cf
configuration file, as described in the next section. However,
at this point you can test that the zino
command is available to run:
$ zino --help
usage: zino [-h] [--polldevs PATH] [--debug] [--stop-in N] [--trap-port PORT] [--user USER]
Zino is not OpenView
options:
-h, --help show this help message and exit
--polldevs PATH Path to polldevs.cf
--debug Set global log level to DEBUG. Very chatty!
--stop-in N Stop zino after N seconds.
--trap-port PORT Which UDP port to listen for traps on. Default value is 162. Any value below 1024 requires root privileges. Setting to 0
disables SNMP trap monitoring.
--user USER Switch to this user immediately after binding to privileged ports
Even if the Python virtual environment hasn't been activated in your shell, you can still run Zino directly from inside this environment, like so:
./zino-env/bin/zino --help
By default, Zino will listen for incoming SNMP traps on UDP port 162
. This
port is privileged (less than 1024), however, which means that Zino needs to
be started as root
if you want to receive traps. In order to avoid running
continuously with root
privileges, the --user
option can be used to tell
Zino to switch to running as a less privileged user as soon as port 162
has
been acquired.
Alternately, you can tell Zino to listen for traps on a non-privileged port,
e.g. by adding --trap-port 1162
to the command line arguments, but this only
works if you can configure your SNMP agents to send traps to this non-standard
port. In any case, you can also tell Zino to skip listening for traps by
specifying --trap-port 0
.
At minimum, Zino must be configured with a list of SNMP-enabled routers to
monitor. By default, it looks for polldevs.cf
in the current working
directory, but a different configuration file can be specified using the
--polldevs
command line option.
See the polldevs.cf.example file for an example of the configuration format.
Zino will check polldevs.cf
for changes on a scheduled interval while it's
running, so any changes made while Zino is running should be picked up without
requiring a restart of the process.
Other settings can be also configured in a separate TOML file,
which defaults to zino.toml
in the current working directory, but a different file
can be specified using the --config-file
command line option.
See the zino.toml.example file for the settings that can be configured and their default values.
Zino does not currently check zino.toml
for changes on a scheduled interval while
it's running, so Zino needs to be restarted for changes to take effect.
Zino 2 reimplements the text-based (vaguely SMTP-esque) API protocol from Zino
1, warts and all. This means that the protocol runs over unencrypted TCP
sessions. Access to restricted API information requires authentication through
the USER
command. Usernames and passwords are configured in cleartext in a
secrets
file, e.g.:
user1 password123
user2 my-pets-name
You should therefore ensure that the secrets
file is only readable for the
user that the zino
command runs as.
Please note that passwords are not transmitted in cleartext over API socket connections. The Zino server protocol utilizes a challenge-response mechanism, in which the user logging in must prove that they know the password by giving a correct response to the given challenge.
When opening a connection to the API port, the Zino server will immediately send a hello message with a session challenge included:
$ telnet localhost 8001
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
200 6077fe9fa53e4921b35c11cf6ef8891bc0194875 Hello, there
To authenticate properly, the client must issue the USER
command, which has
two arguments: A username and a challenge response string. Given the challenge
value from above (6077fe9fa53e4921b35c11cf6ef8891bc0194875
), the proper
challenge response for user1
can be computed on the command line thus:
$ echo -n "6077fe9fa53e4921b35c11cf6ef8891bc0194875 password123" | sha1sum
4daf3c1448c2c4b3b92489024cc4676f70c26b1d -
$
The proper way to authenticate as user1
would then be to issue this command:
USER user1 4daf3c1448c2c4b3b92489024cc4676f70c26b1d
Zino 1 stores its running state to disk as a piece of Tcl code (usually in
save-state.tcl
). Zino 2 stores its running state in a JSON formatted file
(usually in zino-state.json
). These two files are not compatible. In order
to assist in converting a running Zino 1 system into a Zino 2 system, we have
provided the zinoconv
program, which attempts to read save-state.tcl
and
convert it into a valid zino-state.json
.
This converter is not yet fully tested in all situations, and may have bugs.
Also, Zino 1 has had bugs, and for a long-running Zino 1 system, the
save-state.tcl
file may contain bits of outdated, useless or incorrectly
formatted data (incorrectly formatted IPv6 addresses is one of these known
issues). The zinoconv
program may output lots of warnings about broken Zino
1 data it will ignore.
To convert a save-state.tcl
to zino-state.json
, you can use the command
like so:
zinoconv save-state.tcl zino-state.json
tox and pytest are used to run the test suite. To run the test suite on all supported versions of Python, run:
tox
Zino code should follow the PEP-8 and PEP-257 guidelines. Black and isort are used for automatic code formatting. The pre-commit tool is used to enforce code styles at commit-time.
Before you start hacking, enable pre-commit hooks in your cloned repository, like so:
pre-commit install
Running Zino during development might look like this (listening for traps on the non-privileged port 1162):
zino --trap-port 1162
To send an example trap (BGP4-MIB::bgpBackwardTransition
, which Zino ignores
by default), you can use a command like:
snmptrap -v2c -c public \
127.0.0.1:1162 \
'' \
BGP4-MIB::bgpBackwardTransition \
BGP4-MIB::bgpPeerRemoteAddr a 192.168.42.42 \
BGP4-MIB::bgpPeerLastError x 4242 \
BGP4-MIB::bgpPeerState i 2
To be able to automatically produce the changelog for a release one file for each
pull request (also called news fragment) needs to be added to the folder
changelog.d/
.
The name of the file consists of three parts separated by a period:
- The identifier: the issue number
or the pull request number. If we don't want to add a link to the resulting changelog
entry then a
+
followed by a unique short description. - The type of the change: we use
security
,removed
,deprecated
,added
,changed
andfixed
. - The file suffix, e.g.
.md
, towncrier does not care which suffix a fragment has.
So an example for a file name related to an issue/pull request would be 214.added.md
or for a file without corresponding issue +fixed-pagination-bug.fixed.md
.
This file can either be created manually with a file name as specified above and the changelog text as content or one can use towncrier to create such a file as following:
$ towncrier create -c "Changelog content" 214.added.md
When opening a pull request there will be a check to make sure that a news fragment is added and it will fail if it is missing.
To add all content from the changelog.d/
folder to the changelog file simply run
$ towncrier build --version {version}
This will also delete all files in changelog.d/
.
To preview what the addition to the changelog file would look like add the flag
--draft
. This will not delete any files or change CHANGELOG.md
. It will only output
the preview in the terminal.
A few other helpful flags:
date DATE
- set the date of the release, default is todaykeep
- do not delete the files inchangelog.d/
More information about towncrier.