Metadata-Version: 2.4
Name: zino-argus-glue
Version: 0.4.0
Summary: Argus glue service for Zino
Author-email: Sikt - Norwegian Agency for Shared Services in Education and Research <kontakt@sikt.no>
Maintainer-email: Morten Brekkevold <morten.brekkevold@sikt.no>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Uninett/zino-argus-glue
Project-URL: Changelog, https://github.com/Uninett/zino-argus-glue/blob/master/CHANGELOG.md
Platform: any
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Networking :: Monitoring
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: argus-api-client
Requires-Dist: pysnmp~=6.2
Requires-Dist: requests
Requires-Dist: pydantic<2.11
Requires-Dist: zinolib>=1.3.4
Requires-Dist: tomli; python_version < "3.11"
Dynamic: license-file

# Zino ↔ Argus glue service

This is a [glue
service](https://argus-server.readthedocs.io/en/latest/integrations/glue-services/index.html)
for integration between [Argus](https://github.com/Uninett/Argus), the alert
aggregation server, and [Zino](https://github.com/Uninett/zino), the network
state monitor provided by Sikt.

This is still a work in progress and more information will be added here later.

## Installing zino-argus-glue

### From Python Package Index (PyPI)

```console
$ pip install zino-argus-glue
...
$ zinoargus --help
usage: zinoargus [-h] [-v] [-c CONFIG_FILE]

options:
  -h, --help            show this help message and exit
  -v, --verbose
  -c CONFIG_FILE, --config-file CONFIG_FILE
$
```

### From source (this repository)

```console
$ pip install .
...
$ zinoargus --help
usage: zinoargus [-h] [-v] [-c CONFIG_FILE]

options:
  -h, --help            show this help message and exit
  -v, --verbose
  -c CONFIG_FILE, --config-file CONFIG_FILE
$
```

## Configuring zino-argus-glue

The `zino-argus-glue` program needs to know how to connect to both a Zino API
server and an Argus API server in order to synchronize incidents from Zino to
Argus.  Addresses and authentication tokens for these APIs are configured in
`zinoargus.toml`.  `zinoargus` reads this file the current working directory,
or you can specify an alternate path to a configuration file using the `-c`
command line option.  See [zinoargus.toml.example](./zinoargus.toml.example)
for an example configuration file.

## Primary/secondary failover

`zino-argus-glue` can run as a secondary instance that monitors a primary Zino
server and only takes over Argus synchronization only when the primary becomes
unreachable.  The secondary polls the primary's SNMP agent for its uptime at
regular intervals; after a configurable number of consecutive failures it
switches from `STANDBY` to `ACTIVE` and begins syncing.  When the primary
recovers (the same number of consecutive successes), it switches back to
STANDBY.

A complete failover deployment therefore consists of two independent Zino
servers (each with its own state) and two `zino-argus-glue` instances.  Each
glue instance connects to its own local Zino, and the secondary glue
additionally pings the *primary* Zino's SNMP agent to decide whether to be
active.

To enable failover, add a `[failover]` section to your configuration file:

```toml
[failover]
primary_server = "10.0.0.1"
primary_snmp_port = 8000
snmp_community = "public"
ping_timeout = 5
threshold = 10
```

- `primary_server` — hostname or IP of the primary Zino's SNMP agent
  (required)
- `primary_snmp_port` — UDP port of the SNMP agent (default `8000`)
- `snmp_community` — SNMP community string (default `"public"`)
- `ping_timeout` — timeout in seconds for each SNMP query (default `5`)
- `threshold` — number of consecutive failures before activating, and
  consecutive successes before standing down (default `10`)

When the `[failover]` section is omitted, the daemon runs in standalone
(always-active) mode, which is the default behavior.

### Verifying failover manually

To exercise the failover logic end-to-end:

1. Start the secondary `zino-argus-glue` with a `[failover]` section pointing
   at the primary Zino's SNMP agent.  It should log that it is starting in
   `STANDBY` mode.
2. Stop the primary Zino process.  After `threshold` consecutive ping failures
   the secondary should log a transition to `ACTIVE` and begin syncing its
   own Zino's cases to Argus.
3. Restart the primary Zino.  After `threshold` consecutive successful pings
   the secondary should log a transition back to `STANDBY` and stop syncing.

A low `threshold` (e.g. `3`) is convenient for testing; production deployments
will typically want a higher value to avoid flapping.

## Copying

Copyright 2025-2026 Sikt (The Norwegian Agency for Shared Services in Education and
Research)

Licensed under the Apache License, Version 2.0; See [LICENSE](./LICENSE) for a
full copy of the License.

## Developing Zino-Argus-Glue

### Using towncrier to automatically produce the changelog
#### Before merging a pull request
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:
1. 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.
2. The type of the change: we use `security`, `removed`, `deprecated`, `added`,
`changed` and `fixed`.
3. 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:

```console
$ 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.

#### Before a release
To add all content from the `changelog.d/` folder to the changelog file simply run
```console
$ 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 today
- `keep` - do not delete the files in `changelog.d/`

More information about [towncrier](https://towncrier.readthedocs.io).
